axis-synome 0.1.0.dev63__tar.gz → 0.1.0.dev64__tar.gz

{axis_synome-0.1.0.dev63/src/axis_synome.egg-info → axis_synome-0.1.0.dev64}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: axis-synome
-Version: 0.1.0.dev63
+Version: 0.1.0.dev64
 Summary: Axis specification modules (entities, formulas, validators)
 Author-email: Archon Tech <hello@archontech.ai>
 License: MIT
@@ -86,6 +86,27 @@ 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/`](./examples/README.md). Run any of them with:
+
+```bash
+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 `Position`s 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.

{axis_synome-0.1.0.dev63 → axis_synome-0.1.0.dev64}/README.md

@@ -71,6 +71,27 @@ 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/`](./examples/README.md). Run any of them with:
+
+```bash
+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 `Position`s 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.

axis_synome-0.1.0.dev64/examples/01_prime_basics.py

@@ -0,0 +1,31 @@
+# ruff: noqa: T201
+# Examples are runnable scripts; printing is the whole point.
+"""Example 01 — Basic facts about a Prime.
+
+A ``PrimeAgent`` is an enum whose ``.value`` is a ``PrimeAgentData`` dataclass
+carrying the operational facts of a Sky Star Agent (prime): its name, the
+assets it controls, the networks it operates on, its PSM protocols, and a
+few ASC-specific knobs.
+
+This example walks every prime and prints those facts.
+"""
+
+from axis_synome.spec.asc.entities.primes import PrimeAgent
+
+
+def main() -> None:
+    for prime in PrimeAgent:
+        data = prime.value
+        print(f"=== {data.name} ===")
+        print(f"  asc_exempt              : {data.asc_exempt}")
+        print(f"  # assets                : {len(data.assets)}")
+        print(f"  networks                : {sorted(n.value for n in data.networks)}")
+        print(f"  psm_protocols           : {sorted(p.value for p in data.psm_protocols)}")
+        print(f"  alm_proxy               : {data.alm_proxy.value if data.alm_proxy else None}")
+        print(f"  max_pct_latent_asc      : {data.max_pct_latent_asc}")
+        print(f"  min_pct_asc_of_collat   : {data.min_pct_asc_of_collateral}")
+        print()
+
+
+if __name__ == "__main__":
+    main()

axis_synome-0.1.0.dev64/examples/02_assets_and_tokens_of_a_prime.py

@@ -0,0 +1,77 @@
+# ruff: noqa: T201
+"""Example 02 — Find the assets and tokens associated with a prime.
+
+This is the headline question: *"What does Spark hold?"*
+
+It demonstrates several useful projections off ``PrimeAgentData.assets``:
+
+* the raw list of ``Asset`` rows,
+* the set of ``Token`` symbols held (e.g. ``USDC``, ``sUSDe``, ...),
+* the set of *underlying* tokens (the real economic exposure behind a
+  wrapped/yield-bearing asset),
+* assets grouped by ``Network``,
+* assets grouped by ``Protocol``.
+
+All of this is pure attribute access on the entity graph — no I/O, no
+external lookups.
+"""
+
+from collections import defaultdict
+
+from axis_synome.spec.asc.entities.assets import Asset
+from axis_synome.spec.asc.entities.networks import Network
+from axis_synome.spec.asc.entities.primes import PrimeAgent
+from axis_synome.spec.asc.entities.protocol_sets import Protocol
+
+
+def show_assets_for(prime: PrimeAgent) -> None:
+    data = prime.value
+    print(f"=== {data.name} ===")
+    print(f"Total assets: {len(data.assets)}\n")
+
+    # 1. Direct list of assets.
+    print("Assets (token @ protocol on network):")
+    for asset in data.assets:
+        print(f"  - {asset.token.value:<20} @ {asset.protocol.value:<35} on {asset.network.value}")
+    print()
+
+    # 2. Set of tokens held.
+    tokens_held = {a.token for a in data.assets}
+    print(f"Distinct tokens held ({len(tokens_held)}):")
+    print("  " + ", ".join(sorted(t.value for t in tokens_held)))
+    print()
+
+    # 3. Set of underlying tokens (real economic exposure).
+    underlying = {a.underlying_asset for a in data.assets}
+    print(f"Distinct underlying tokens ({len(underlying)}):")
+    print("  " + ", ".join(sorted(t.value for t in underlying)))
+    print()
+
+    # 4. Group by network.
+    by_network: dict[Network, list[Asset]] = defaultdict(list)
+    for a in data.assets:
+        by_network[a.network].append(a)
+    print("Assets grouped by network:")
+    for network in sorted(by_network, key=lambda n: n.value):
+        tokens = sorted(a.token.value for a in by_network[network])
+        print(f"  {network.value:<20} ({len(tokens)}): {', '.join(tokens)}")
+    print()
+
+    # 5. Group by protocol.
+    by_protocol: dict[Protocol, list[Asset]] = defaultdict(list)
+    for a in data.assets:
+        by_protocol[a.protocol].append(a)
+    print("Assets grouped by protocol:")
+    for protocol in sorted(by_protocol, key=lambda p: p.value):
+        tokens = sorted(a.token.value for a in by_protocol[protocol])
+        print(f"  {protocol.value:<40} ({len(tokens)}): {', '.join(tokens)}")
+    print()
+
+
+def main() -> None:
+    show_assets_for(PrimeAgent.SPARK)
+    show_assets_for(PrimeAgent.GROVE)
+
+
+if __name__ == "__main__":
+    main()

axis_synome-0.1.0.dev64/examples/03_inverse_lookups.py

@@ -0,0 +1,85 @@
+# ruff: noqa: T201
+"""Example 03 — Inverse lookups across the entity graph.
+
+The previous examples ask "given a prime, what does it hold?". This file
+goes the other direction:
+
+* Given a ``Token``, which primes hold it (and via which protocol/network)?
+* Given a ``Network``, which primes operate on it?
+* Given an EVM address, which prime owns the matching asset?
+
+These queries are simple comprehensions over ``PrimeAgent`` and its
+``.value.assets`` list.
+"""
+
+from axis_synome.spec.asc.entities.networks import Network
+from axis_synome.spec.asc.entities.primes import PrimeAgent
+from axis_synome.spec.asc.entities.tokens import Token
+from axis_synome.spec_support.evm_address import EvmAddress
+
+
+def primes_holding_token(token: Token) -> list[tuple[PrimeAgent, list[str]]]:
+    """Return ``(prime, [contexts])`` pairs for every prime holding ``token``.
+
+    ``contexts`` strings have the form ``"<protocol> on <network>"``.
+    """
+    matches: list[tuple[PrimeAgent, list[str]]] = []
+    for prime in PrimeAgent:
+        contexts: list[str] = [
+            f"{a.protocol.value} on {a.network.value}"
+            for a in prime.value.assets
+            if a.token == token
+        ]
+        if contexts:
+            matches.append((prime, contexts))
+    return matches
+
+
+def primes_on_network(network: Network) -> list[PrimeAgent]:
+    return [p for p in PrimeAgent if network in p.value.networks]
+
+
+def prime_owning_address(address: EvmAddress) -> tuple[PrimeAgent, str] | None:
+    for prime in PrimeAgent:
+        for asset in prime.value.assets:
+            if asset.address == address:
+                return prime, asset.token.value
+    return None
+
+
+def main() -> None:
+    print("=== Primes holding USDC ===")
+    for prime, contexts in primes_holding_token(Token.USDC):
+        print(f"  {prime.value.name}:")
+        for ctx in contexts:
+            print(f"    - {ctx}")
+    print()
+
+    print("=== Primes holding JAAA ===")
+    for prime, contexts in primes_holding_token(Token.JAAA):
+        print(f"  {prime.value.name}: {', '.join(contexts)}")
+    print()
+
+    print("=== Primes operating on Base ===")
+    for prime in primes_on_network(Network.BASE):
+        print(f"  - {prime.value.name}")
+    print()
+
+    print("=== Primes operating on Avalanche ===")
+    for prime in primes_on_network(Network.AVALANCHE):
+        print(f"  - {prime.value.name}")
+    print()
+
+    # Reverse lookup by EVM address — pick a real one from Grove's JAAA holding.
+    probe = EvmAddress("0x1121F4e21eD8B9BC1BB9A2952cDD8639aC897784")
+    print(f"=== Owner of address {probe} ===")
+    hit = prime_owning_address(probe)
+    if hit is None:
+        print("  (no match)")
+    else:
+        prime, token_name = hit
+        print(f"  {prime.value.name} (token: {token_name})")
+
+
+if __name__ == "__main__":
+    main()

axis_synome-0.1.0.dev64/examples/04_atlas_provenance.py

@@ -0,0 +1,36 @@
+# ruff: noqa: T201
+"""Example 04 — Atlas provenance for every asset.
+
+Every ``Asset`` carries two ``source`` strings: ``source`` (the Atlas
+document number defining the wrapped/listed asset) and
+``underlying_asset_source`` (the document defining the underlying token).
+These are dot-separated identifiers like ``A.6.1.1.2.2.6.1.3.2.1.2.2.2.1``
+that resolve to documents under ``content/`` (validated by the
+``check-spec-uuids`` make target).
+
+This example prints the provenance trail for each asset of a prime, so a
+reviewer can jump straight from the spec entity to the Atlas document that
+authorizes it.
+"""
+
+from axis_synome.spec.asc.entities.primes import PrimeAgent
+
+
+def show_provenance(prime: PrimeAgent) -> None:
+    print(f"=== {prime.value.name} — asset provenance ===")
+    for asset in prime.value.assets:
+        print(f"  {asset.token.value} on {asset.network.value} via {asset.protocol.value}")
+        print(f"    address                  : {asset.address}")
+        print(f"    Atlas doc (asset)        : {asset.source}")
+        print(f"    underlying token         : {asset.underlying_asset.value}")
+        print(f"    underlying address       : {asset.underlying_asset_address}")
+        print(f"    Atlas doc (underlying)   : {asset.underlying_asset_source}")
+        print()
+
+
+def main() -> None:
+    show_provenance(PrimeAgent.GROVE)
+
+
+if __name__ == "__main__":
+    main()

axis_synome-0.1.0.dev64/examples/05_feeding_a_formula.py

@@ -0,0 +1,91 @@
+# ruff: noqa: T201
+"""Example 05 — Bridge external records into Positions and call a formula.
+
+Once you know the *associated concepts* of a prime (examples 02 and 03),
+the next step is feeding real-world holdings into a formula. This example
+shows the canonical bridge pattern:
+
+1. External data arrives as plain dicts (API response, CSV row, DB record).
+2. ``record_to_position`` resolves token/protocol/network strings to enums
+   and builds ``Asset`` + ``Position`` instances.
+3. We hand the resulting ``list[Position]`` to ``asc(...)`` to get a USD total.
+
+The bridge intentionally lives outside the spec subset (which forbids I/O
+and string→enum coercion). Only the formulas it feeds into are constrained.
+
+Note: ``asc(...)`` requires the ``axis-synome[runtime]`` extra (numpy-backed
+``ReferenceSpecRuntime``). It is installed in this repo's dev environment.
+"""
+
+from axis_synome.spec.asc.entities.asset_categories import AssetCategory
+from axis_synome.spec.asc.entities.assets import Asset
+from axis_synome.spec.asc.entities.networks import Network
+from axis_synome.spec.asc.entities.primes import EligiblePrimeAgentASC
+from axis_synome.spec.asc.entities.protocol_sets import Protocol
+from axis_synome.spec.asc.entities.tokens import Token
+from axis_synome.spec.asc.entities.types import Position
+from axis_synome.spec.asc.formulas.asc import asc
+from axis_synome.spec_support.evm_address import EvmAddress
+
+# A single placeholder address; real callers would pass the on-chain address
+# of the holding (e.g., the LitePSM, the Curve pool, the Aave aToken, ...).
+MOCK_ADDRESS = EvmAddress("0x1121F4e21eD8B9BC1BB9A2952cDD8639aC897784")
+
+
+def record_to_position(rec: dict) -> Position:
+    """Convert a raw record dict to a ``Position``.
+
+    Required keys: ``token``, ``protocol``, ``network``, ``value_usd``.
+    Optional keys: ``pool_paired_with_usds``, ``fee_tier``.
+    """
+    return Position(
+        asset=Asset(
+            token=Token(rec["token"]),
+            protocol=Protocol(rec["protocol"]),
+            network=Network(rec["network"]),
+            address=MOCK_ADDRESS,
+            underlying_asset=Token(rec["token"]),
+            underlying_asset_address=MOCK_ADDRESS,
+            underlying_asset_source="",
+            categories={AssetCategory.CASH_STABLECOIN},
+        ),
+        value_usd=float(rec["value_usd"]),
+        pool_paired_with_usds=rec.get("pool_paired_with_usds"),
+        fee_tier=rec.get("fee_tier"),
+    )
+
+
+def main() -> None:
+    # Pretend these came from an indexer or a CSV.
+    api_records = [
+        {
+            "token": "USDC",
+            "protocol": "LitePSM",
+            "network": "Ethereum Mainnet",
+            "value_usd": 500_000.0,
+        },
+        {"token": "USDC", "protocol": "PSM3", "network": "Base", "value_usd": 250_000.0},
+        {
+            "token": "USDC",
+            "protocol": "Curve",
+            "network": "Ethereum Mainnet",
+            "value_usd": 300_000.0,
+            "pool_paired_with_usds": True,
+        },
+    ]
+
+    positions = [record_to_position(r) for r in api_records]
+
+    print(f"Built {len(positions)} positions from external records:")
+    for p in positions:
+        print(
+            f"  - {p.asset.token.value:<6} via {p.asset.protocol.value:<10} "
+            f"on {p.asset.network.value:<18} = ${p.value_usd:,.2f}"
+        )
+
+    total_asc = asc(EligiblePrimeAgentASC.SPARK, positions)
+    print(f"\nasc(SPARK, positions) = ${total_asc:,.2f}")
+
+
+if __name__ == "__main__":
+    main()

axis_synome-0.1.0.dev64/examples/README.md

@@ -0,0 +1,58 @@
+# axis-synome examples
+
+Runnable, self-contained scripts that show how to navigate the entity graph
+exposed by `axis_synome.spec` — answering questions like *"what assets does
+Spark hold?"*, *"which primes operate on Base?"*, or *"which Atlas document
+defines this token?"*.
+
+## Overview
+
+The examples are numbered by complexity. Earlier ones introduce the core
+entities; later ones build on them to do reverse lookups, surface Atlas
+provenance, and bridge external data into a real formula call.
+
+Each file is a plain Python script with a module docstring describing what
+it shows and a `main()` that prints to stdout. They use only public imports
+under `axis_synome.spec.asc.entities` and `axis_synome.spec.asc.formulas`,
+and are exercised on every CI run by `tests/axis_synome/test_examples.py`,
+so they cannot silently rot.
+
+Run any of them directly:
+
+```bash
+cd axis-synome
+uv run python examples/02_assets_and_tokens_of_a_prime.py
+```
+
+| File | Question it answers |
+| --- | --- |
+| `01_prime_basics.py` | What does a `PrimeAgent` carry (name, networks, PSM protocols, asset count)? |
+| `02_assets_and_tokens_of_a_prime.py` | Which `Asset`s and `Token`s does a given prime hold, grouped by network and protocol? |
+| `03_inverse_lookups.py` | Which primes hold a given token? Which primes operate on a given network? Which prime owns an address? |
+| `04_atlas_provenance.py` | Which Atlas document defines each asset and its underlying token? |
+| `05_feeding_a_formula.py` | How do I bridge external records (API/CSV/DB rows) into `Position`s and call `asc(...)`? |
+
+## Running specific spec formulas
+
+For end-to-end usage of individual formulas — how to construct the
+expected entity inputs, what the outputs look like, and how to bridge
+external records into the call — read the formula tests under
+`tests/axis_synome/`. They double as worked examples and are the
+authoritative reference for how each formula is meant to be called:
+
+- `tests/axis_synome/asc/test_asc.py` — `asc(prime, positions)` end-to-end,
+  including a bridge from an API-shaped `dict` into `Position`s
+  (`test_bridge_from_api_response`).
+- `tests/axis_synome/asc/test_resting_asc.py`,
+  `test_latent_asc.py`, `test_ratio_latent_asc.py`,
+  `test_asc_collateral_ratio.py`, `test_asc_incentive.py`, `test_dab.py` —
+  one file per ASC sub-formula, each showing the smallest realistic input
+  set that exercises the formula.
+- `tests/axis_synome/asc/mocks.py` — shared fixtures (`spark_resting_positions()`,
+  `spark_latent_positions()`, …) you can copy when building inputs.
+- `tests/axis_synome/suraf/formulas/test_scoring.py`,
+  `tests/axis_synome/suraf/formulas/test_crr.py` — same pattern for the
+  SURAF scoring / collateral-risk-rating formulas.
+
+When adding a new formula, add a `test_<formula>.py` next to the existing
+ones; that test then becomes the worked example for callers.

{axis_synome-0.1.0.dev63 → axis_synome-0.1.0.dev64}/pyproject.toml

@@ -25,6 +25,7 @@ Repository = "https://github.com/archon-research/next-gen-atlas"
 Documentation = "https://github.com/archon-research/next-gen-atlas"
 
 [project.scripts]
+axis-spec-inspect = "axis_synome.spec_inspect.cli:main"
 export_entities = "axis_synome.export_entities:main"
 
 [project.entry-points."flake8.extension"]

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

axis_synome-0.1.0.dev64/src/axis_synome/spec_inspect/__init__.py

@@ -0,0 +1,12 @@
+"""Agent-friendly CLI for inspecting the spec tree.
+
+Run as a module::
+
+    python -m axis_synome.spec_inspect <command> [args...]
+
+See :mod:`axis_synome.spec_inspect.cli` for available subcommands.
+"""
+
+from axis_synome.spec_inspect.cli import main
+
+__all__ = ["main"]

axis_synome-0.1.0.dev64/src/axis_synome/spec_inspect/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from axis_synome.spec_inspect.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())