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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: axis-synome
-Version: 0.1.0.dev71
+Version: 0.1.0.dev72
 Summary: Axis specification modules (entities, formulas, validators)
 Author-email: Archon Tech <hello@archontech.ai>
 License: MIT

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

@@ -79,6 +79,14 @@ select = [
     "ARG",
     "PTH",
     "PGH004",
+    # Public docstring presence — scoped to ``src/axis_synome/spec/**`` via
+    # the per-file-ignores table below. Spec docstrings are the carrier for
+    # ``:source_uuid:`` provenance (see ``WRITING_SPECS.md``); a missing one
+    # is a real bug, not a style nit.
+    "D101",  # missing docstring in public class
+    "D102",  # missing docstring in public method
+    "D103",  # missing docstring in public function
+    "D106",  # missing docstring in public nested class
 ]
 ignore = ["E402", "E501"]
 
@@ -86,3 +94,20 @@ ignore = ["E402", "E501"]
 # put `# ruff: noqa: <CODE>` (file-level) or `# noqa: <CODE>` (line-level) in
 # the source file itself, with a short reason. Keeps the rationale next to the
 # code it justifies and avoids a central table that drifts as files move.
+#
+# Exception: the D101/D102/D103/D106 rules above are conceptually scoped to
+# ``src/axis_synome/spec/**`` only. Ruff has no "select-only-here" syntax, so
+# we disable them everywhere else via the per-file-ignores table below. New
+# top-level directories under ``axis-synome/`` need a row here.
+
+[tool.ruff.lint.per-file-ignores]
+"src/axis_synome/__init__.py" = ["D101", "D102", "D103", "D106"]
+"src/axis_synome/_version.py" = ["D101", "D102", "D103", "D106"]
+"src/axis_synome/export_entities.py" = ["D101", "D102", "D103", "D106"]
+"src/axis_synome/spec_support/**" = ["D101", "D102", "D103", "D106"]
+"src/axis_synome/spec_validator/**" = ["D101", "D102", "D103", "D106"]
+"src/axis_synome/spec_inspect/**" = ["D101", "D102", "D103", "D106"]
+"src/axis_synome/spec/**/examples/**" = ["D101", "D102", "D103", "D106"]
+"examples/**" = ["D101", "D102", "D103", "D106"]
+"**/*.ipynb" = ["D101", "D102", "D103", "D106"]
+"tests/**" = ["D101", "D102", "D103", "D106"]

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

{axis_synome-0.1.0.dev71 → axis_synome-0.1.0.dev72}/src/axis_synome/parser/checks/numeric_fidelity.py

@@ -288,6 +288,7 @@ def _run_case(case: ScalarCase) -> str | None:
 
 
 def main() -> int:
+    """Run the numeric fidelity gate for scalar formulas."""
     cases = _collect_scalar_formula_cases()
     failures: list[tuple[str, str]] = []
     for case in cases:

{axis_synome-0.1.0.dev71 → axis_synome-0.1.0.dev72}/src/axis_synome/parser/converters.py

@@ -51,14 +51,17 @@ _BASE_LOCAL_DICT: dict[str, Any] = {
 
 
 def ensure_sympy_expr(value: sp.Basic) -> sp.Expr:
+    """Coerce a SymPy basic into an expression type."""
     return cast(sp.Expr, value)
 
 
 def ensure_sympy_bool(value: sp.Basic) -> SymBoolean:
+    """Coerce a SymPy basic into a Boolean type."""
     return cast(SymBoolean, value)
 
 
 def convert_python_constant(value: object) -> sp.Basic:
+    """Lower a Python scalar constant to the matching SymPy atom."""
     if isinstance(value, bool):
         return sp.true if value else sp.false
     if isinstance(value, int):
@@ -164,6 +167,7 @@ def get_constant_set(scope: dict[str, Any] | None, name: str) -> list[object] |
 
 
 def lower_unary_operator(op: ast.unaryop, operand: sp.Basic) -> sp.Basic:
+    """Lower a Python unary operator to SymPy."""
     operand_expr = ensure_sympy_expr(operand)
     if isinstance(op, ast.USub):
         return sp.Mul(sp.Integer(-1), operand_expr, evaluate=False)
@@ -175,6 +179,7 @@ def lower_unary_operator(op: ast.unaryop, operand: sp.Basic) -> sp.Basic:
 
 
 def lower_binary_operator(op: ast.operator, left: sp.Basic, right: sp.Basic) -> sp.Basic:
+    """Lower a Python binary operator to SymPy."""
     left_expr = ensure_sympy_expr(left)
     right_expr = ensure_sympy_expr(right)
     if isinstance(op, ast.Add):
@@ -197,6 +202,7 @@ def lower_binary_operator(op: ast.operator, left: sp.Basic, right: sp.Basic) ->
 
 
 def lower_boolean_operator(op: ast.boolop, values: list[sp.Basic]) -> sp.Basic:
+    """Lower a Python boolean operator to SymPy."""
     items = [ensure_sympy_bool(value) for value in values]
     if isinstance(op, ast.And):
         return sp.And(*items)
@@ -213,6 +219,7 @@ def lower_comparison_operator(
     in_handler: Callable[[sp.Basic, sp.Basic], sp.Basic] | None = None,
     not_in_handler: Callable[[sp.Basic, sp.Basic], sp.Basic] | None = None,
 ) -> sp.Basic:
+    """Lower a Python comparison operator to SymPy."""
     if isinstance(op, ast.Gt):
         return sp.Gt(ensure_sympy_expr(left), ensure_sympy_expr(right), evaluate=False)
     if isinstance(op, ast.GtE):

{axis_synome-0.1.0.dev71 → axis_synome-0.1.0.dev72}/src/axis_synome/parser/entity_parser.py

@@ -34,6 +34,8 @@ _STATIC_SCOPE_KEY = "\x00static_scope"
 
 
 class StatementRole(StrEnum):
+    """Role assigned to a lowered statement identity."""
+
     INPUT = "input"
     DERIVED = "derived"
     OUTPUT = "output"
@@ -41,6 +43,8 @@ class StatementRole(StrEnum):
 
 @dataclass
 class StatementIdentity:
+    """A single lowered statement in the identity graph."""
+
     identity: str
     expr: str
     deps: list[str]
@@ -69,6 +73,7 @@ class SymbolicStruct(sp.Expr):
     precedence = _PRECEDENCE["Atom"]
 
     def __new__(cls, name: str):
+        """Create a symbolic stand-in for chained access expressions."""
         obj = super().__new__(cls)
         obj._struct_name = name
         # Initialise the SymPy internal ``_args`` slot so traversal
@@ -99,6 +104,8 @@ class SymbolicStruct(sp.Expr):
 
 
 class ContainsBool(sp.logic.boolalg.BooleanFunction):
+    """Opaque boolean wrapper for membership tests."""
+
     nargs = 2
 
     @override
@@ -213,10 +220,13 @@ def has_entity_params(func: FunctionType) -> bool:
 
 
 class IdentityProgramBuilder:
+    """Lower a spec function body into statement identities."""
+
     def __init__(self, func: FunctionType) -> None:
         self.func = func
 
     def build(self) -> tuple[list[StatementIdentity], str]:
+        """Build the statement identity sequence and return expression."""
         source = inspect.getsource(self.func)
         tree = ast.parse(source)
         func_def = next(node for node in tree.body if isinstance(node, ast.FunctionDef))
@@ -671,6 +681,7 @@ def reconstruct_sympy_expression(
     statements: list[StatementIdentity],
     module_globals: dict[str, Any] | None = None,
 ) -> sp.Basic:
+    """Reconstruct the final SymPy expression from lowered statements."""
     env: dict[str, sp.Basic] = {}
     if module_globals is not None:
         # Carry module globals alongside the substitution environment so the

{axis_synome-0.1.0.dev71 → axis_synome-0.1.0.dev72}/src/axis_synome/parser/formula_extraction.py

@@ -38,6 +38,8 @@ _processed_modules: set[str] = set()
 
 
 class FormulaCodegenMetadata(TypedDict):
+    """Metadata captured for generated formula code."""
+
     codegen_source_module: str | None
     codegen_source_symbol: str | None
     codegen_imports: list[str]

{axis_synome-0.1.0.dev71 → axis_synome-0.1.0.dev72}/src/axis_synome/parser/identity.py

@@ -307,59 +307,73 @@ class IdentityData:
 
     @property
     def fqn(self) -> str:
+        """Return the canonical fully qualified name."""
         return self._fqn
 
     @property
     def formula_id(self) -> str:
+        """Return the formula identifier, falling back to node_id."""
         return self._formula_id or self.node_id
 
     @property
     def parameter_id(self) -> str:
+        """Return the parameter identifier, falling back to node_id."""
         return self._parameter_id or self.node_id
 
     @property
     def symbol(self) -> str:
+        """Return the exposed symbol name."""
         return self.node_id
 
     @property
     def output_units(self) -> str | None:
+        """Return the canonical output units."""
         return self.units
 
     @property
     def default_value(self) -> SupportedParameterType | None:
+        """Return the canonical default value."""
         return self.value
 
     @property
     def value_type(self) -> str:
+        """Return the scalar type name for the stored value."""
         return infer_value_type(self.value) or "float"
 
     # Codegen metadata convenience properties
     @property
     def codegen_source_module(self) -> str | None:
+        """Return the originating source module for code generation."""
         return self.codegen.source_module
 
     @property
     def codegen_source_symbol(self) -> str | None:
+        """Return the originating source symbol for code generation."""
         return self.codegen.source_symbol
 
     @property
     def codegen_symbol_kind(self) -> str | None:
+        """Return the kind of source symbol used for code generation."""
         return self.codegen.symbol_kind
 
     @property
     def codegen_type_expr(self) -> str | None:
+        """Return the generated type expression, if any."""
         return self.codegen.type_expr
 
     @property
     def codegen_default_expr(self) -> str | None:
+        """Return the generated default expression, if any."""
         return self.codegen.default_expr
 
     @property
     def codegen_imports(self) -> list[str]:
+        """Return the imports required by generated code."""
         return self.codegen.imports
 
     @classmethod
     def from_dict(cls, doc: dict[str, Any]) -> Self:
+        """Build an identity from a raw document mapping."""
         expression = doc.get("expression") or doc.get("expression_ast")
         return cls(
             node_id=str(doc.get("node_id") or doc.get("formula_id") or doc.get("parameter_id")),
@@ -378,6 +392,7 @@ class IdentityData:
         )
 
     def evaluate(self, values: dict[str, float]) -> float:
+        """Evaluate the SymPy expression with the provided substitutions."""
         if self.sympy_expr is None:
             raise ValueError(f"Identity '{self.node_id}' has no expression to evaluate")
         symbol_values = {sp.Symbol(k): sp.Float(v) for k, v in values.items()}
@@ -385,6 +400,7 @@ class IdentityData:
         return float(expr.subs(symbol_values).evalf())
 
     def to_dict(self) -> dict[str, object]:
+        """Serialize the identity to a document mapping."""
         doc: dict[str, object] = {
             "@type": "Identity",
             "@id": f"Identity/{self.node_id}",

{axis_synome-0.1.0.dev71 → axis_synome-0.1.0.dev72}/src/axis_synome/parser/latex/render.py

@@ -34,6 +34,7 @@ class FormulaPiece:
 
     @property
     def latex(self) -> str:
+        """Return the rendered equality as a single LaTeX string."""
         return f"{self.head} = {self.body}"
 
 

{axis_synome-0.1.0.dev71 → axis_synome-0.1.0.dev72}/src/axis_synome/parser/statement_handler.py

@@ -309,6 +309,7 @@ class StatementHandler:
         return [element_formula, final_formula]
 
     def handle_for_loop(self, _for_stmt: ast.For):
+        """Reject for-loops, which are not supported for SymPy lowering."""
         raise NotImplementedError(
             "For-loops are not convertible to SymPy expressions; "
             "specs must use comprehensions (sum, list, etc.) or function composition instead. "
@@ -325,6 +326,7 @@ class StatementHandler:
         formulas: list,
         codegen_formula_metadata: dict[str, str | list[str] | None] | None = None,
     ) -> list:
+        """Lower the return statement into one or more output formulas."""
         if return_stmt.value is None:
             raise ValueError("Return statement has no value")
 

{axis_synome-0.1.0.dev71 → axis_synome-0.1.0.dev72}/src/axis_synome/spec/asc/entities/assets.py

@@ -12,6 +12,14 @@ from axis_synome.spec_support.validated_dataclass import validated_dataclass
 
 @validated_dataclass
 class Asset:
+    """An on-chain position held against a single ``(token, network, protocol)`` triple.
+
+    Carries the position's contract address plus the underlying token it
+    represents (relevant for wrapped/derived assets like aTokens or
+    erc4626 vault shares) and a non-empty set of ``AssetCategory`` tags
+    that drive eligibility checks in the ASC / DAB calculations.
+    """
+
     token: Token
     network: Network
     protocol: Protocol

{axis_synome-0.1.0.dev71 → axis_synome-0.1.0.dev72}/src/axis_synome/spec/asc/entities/networks.py

@@ -2,6 +2,13 @@ from enum import Enum
 
 
 class Network(Enum):
+    """Blockchain networks where Sky-tracked assets can live.
+
+    Members serve as the canonical identifier on every ``Asset`` and drive
+    L1/L2 classification (``L2_NETWORKS``) and STL exporter chain labels
+    (``STL_CHAIN_BY_NETWORK``).
+    """
+
     ETHEREUM_MAINNET = "Ethereum Mainnet"
     BASE = "Base"
     ARBITRUM = "Arbitrum"

{axis_synome-0.1.0.dev71 → axis_synome-0.1.0.dev72}/src/axis_synome/spec/asc/entities/protocol_sets.py

@@ -2,6 +2,15 @@ from enum import Enum, StrEnum
 
 
 class Protocol(Enum):
+    """All protocols recognised as venues for Sky-tracked assets.
+
+    Membership in the module-level protocol sets below
+    (``LENDING_PROTOCOLS``, ``L1_PSM_PROTOCOLS``, ``L2_PSM_PROTOCOLS``,
+    ``POOL_PROTOCOLS``, ``ATOKEN_PROTOCOLS``, ``ERC4626_PROTOCOLS``, …)
+    selects the protocol class that drives ASC eligibility, Latent ASC
+    classification, and STL exporter behaviour.
+    """
+
     # PSM
     LITE_PSM = "LitePSM"
     PSM3 = "PSM3"

{axis_synome-0.1.0.dev71 → axis_synome-0.1.0.dev72}/src/axis_synome/spec/asc/entities/tokens.py

@@ -2,6 +2,14 @@ from enum import Enum
 
 
 class Token(Enum):
+    """Every token symbol referenced by spec entities and constants.
+
+    Members appear on ``Asset.token`` / ``Asset.underlying_asset`` and in
+    category sets such as ``CASH_STABLECOINS``, ``DIRECT_ETHENA_TOKENS``,
+    and ``PENDLE_ETHENA_TOKENS`` that drive token-class-specific
+    calculations.
+    """
+
     USDC = "USDC"
     USDS = "USDS"
     DAI = "DAI"

{axis_synome-0.1.0.dev71 → axis_synome-0.1.0.dev72}/src/axis_synome/spec/codegen_test/entities/agents.py

@@ -3,6 +3,13 @@ from dataclasses import dataclass, field
 
 @dataclass
 class SampleAgent:
+    """Minimal agent fixture used by the ``codegen_test`` package only.
+
+    Carries no Atlas semantics; it exists to give the entity-codegen tests a
+    small, stable dataclass to round-trip without depending on any
+    production spec entity.
+    """
+
     name: str
     proxy: str | None = None
     output_tokens: set[str] = field(default_factory=set)

{axis_synome-0.1.0.dev71 → axis_synome-0.1.0.dev72}/src/axis_synome/spec/entities/audit_firms.py

@@ -33,6 +33,15 @@ MID_TIER_EFFECTIVENESS_COEFFICIENT: Final[float] = 0.5
 
 @dataclass
 class AuditFirmData:
+    """Per-firm payload attached to each ``AuditFirm`` enum member.
+
+    Bundles the firm's display name, its tier (``TOP_TIER`` /
+    ``MID_TIER``), and the effectiveness coefficient consumed by the
+    Audit Factor formula. Storing this as the enum value keeps a single
+    point of truth: changing a firm's tier updates its coefficient
+    everywhere automatically.
+    """
+
     name: str
     tier: AuditFirmTier
     effectiveness_coefficient: float
@@ -280,6 +289,14 @@ MID_TIER_AUDIT_FIRMS: Final[set[AuditFirm]] = {
 
 @validated_dataclass
 class AuditRecord:
+    """A single audit performed on a protocol by a recognised ``AuditFirm``.
+
+    The covered/total line counts give the audit's coverage ratio and the
+    age (in years) gives its decay factor; together with the firm's
+    effectiveness coefficient they feed the Audit Factor calculation
+    (Atlas ``A.3.2.2.1.2.2.5``).
+    """
+
     firm: AuditFirm
     lines_of_code_covered: Annotated[int, Field(ge=0)]
     """Lines of code covered by this audit.

{axis_synome-0.1.0.dev71 → axis_synome-0.1.0.dev72}/src/axis_synome/spec/entities/smart_contract_risk.py

@@ -12,6 +12,17 @@ from axis_synome.spec_support.validated_dataclass import validated_dataclass
 
 @validated_dataclass
 class SmartContract:
+    """A single smart contract under a protocol, with the code-complexity
+    inputs consumed by Smart Contract RRC.
+
+    The five complexity metrics (cyclomatic complexity, decision points,
+    external calls, inheritance depth, lines of code) are aggregated
+    across a protocol's covered contracts to feed Raw Code Complexity
+    Rating (Atlas ``A.3.2.2.1.2.2.3.3``); ``deployment_age_days`` feeds
+    the Lindy Adjustment Factor; ``upgradeable`` is captured for
+    forward compatibility.
+    """
+
     id: str
     chain: Network
     deployment_age_days: Annotated[float, Field(ge=0.0)]
@@ -101,6 +112,15 @@ class ProtocolSmartContractProfile:
 
 @validated_dataclass
 class CapitalMappingScenario:
+    """Per-protocol exposure/collateral snapshot consumed by the Capital
+    Mapping step of the Smart Contract RRC calculation.
+
+    Splits total exposure (``e_tot``) into the portion absorbed by the
+    protocol's internal liquid surplus (``e_int`` / ``s_liq``) and the
+    portion that spills beyond it (``e_beyond``), against total
+    collateral (``c_tot``).
+    """
+
     e_int: Annotated[float, Field(ge=0.0)]
     """Internal Exposure: exposure that the protocol's internal liquid surplus
     can absorb.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: axis-synome
-Version: 0.1.0.dev71
+Version: 0.1.0.dev72
 Summary: Axis specification modules (entities, formulas, validators)
 Author-email: Archon Tech <hello@archontech.ai>
 License: MIT

{axis_synome-0.1.0.dev71 → axis_synome-0.1.0.dev72}/src/axis_synome.egg-info/SOURCES.txt

@@ -40,6 +40,7 @@ src/axis_synome/parser/latex/render.py
 src/axis_synome/spec/__init__.py
 src/axis_synome/spec/all_entities/__init__.py
 src/axis_synome/spec/all_entities/lending_markets.py
+src/axis_synome/spec/asc/__init__.py
 src/axis_synome/spec/asc/entities/__init__.py
 src/axis_synome/spec/asc/entities/alm_proxies.py
 src/axis_synome/spec/asc/entities/asset_categories.py
@@ -51,6 +52,7 @@ src/axis_synome/spec/asc/entities/primes.py
 src/axis_synome/spec/asc/entities/protocol_sets.py
 src/axis_synome/spec/asc/entities/tokens.py
 src/axis_synome/spec/asc/entities/types.py
+src/axis_synome/spec/asc/formulas/__init__.py
 src/axis_synome/spec/asc/formulas/asc.py
 src/axis_synome/spec/asc/formulas/asc_collateral_ratio.py
 src/axis_synome/spec/asc/formulas/asc_incentive.py
@@ -58,6 +60,8 @@ src/axis_synome/spec/asc/formulas/dab.py
 src/axis_synome/spec/asc/formulas/latent_asc.py
 src/axis_synome/spec/asc/formulas/ratio_latent_asc.py
 src/axis_synome/spec/asc/formulas/resting_asc.py
+src/axis_synome/spec/codegen_test/__init__.py
+src/axis_synome/spec/codegen_test/entities/__init__.py
 src/axis_synome/spec/codegen_test/entities/agents.py
 src/axis_synome/spec/crypto_lending/__init__.py
 src/axis_synome/spec/crypto_lending/formulas/__init__.py
@@ -101,9 +105,12 @@ src/axis_synome/spec/risk_capital/smart_contract_rrc/__init__.py
 src/axis_synome/spec/risk_capital/smart_contract_rrc/exceptions.py
 src/axis_synome/spec/risk_capital/smart_contract_rrc/smart_contract_risk.py
 src/axis_synome/spec/suraf/README.md
+src/axis_synome/spec/suraf/__init__.py
+src/axis_synome/spec/suraf/entities/__init__.py
 src/axis_synome/spec/suraf/entities/assessor_score.py
 src/axis_synome/spec/suraf/entities/assets.py
 src/axis_synome/spec/suraf/entities/mappings.py
+src/axis_synome/spec/suraf/formulas/__init__.py
 src/axis_synome/spec/suraf/formulas/crr.py
 src/axis_synome/spec/suraf/formulas/scoring.py
 src/axis_synome/spec_inspect/__init__.py