wayfinder-paths 0.1.19__py3-none-any.whl → 0.1.21__py3-none-any.whl

wayfinder_paths/adapters/token_adapter/README.md

@@ -1,89 +1,81 @@
 # Token Adapter
 
-A Wayfinder adapter that wraps the `_get_token_via_api` method for fetching token data via HeadlessAPIViewSet endpoints. This adapter supports both address and token_id lookups.
+Adapter for token metadata and price feeds.
 
-## Capabilities
+- **Type**: `TOKEN`
+- **Module**: `wayfinder_paths.adapters.token_adapter.adapter.TokenAdapter`
 
-- `token.read`: Retrieve token information by address or token ID
+## Overview
 
-## Configuration
-
-The adapter uses the TokenClient which automatically handles authentication and API configuration through the Wayfinder settings. No additional configuration is required.
-
-The TokenClient will automatically:
-- Use the WAYFINDER_API_URL from settings
-- Handle authentication via config.json
-- Manage token refresh and retry logic
+The TokenAdapter provides:
+- Token metadata (address, decimals, symbol)
+- Live price data
+- Gas token lookups by chain
 
 ## Usage
 
-### Initialize the Adapter
-
 ```python
 from wayfinder_paths.adapters.token_adapter.adapter import TokenAdapter
 
-# No configuration needed - uses TokenClient with automatic settings
 adapter = TokenAdapter()
 ```
 
-### Get Token Metadata
+## Methods
+
+### get_token
 
-Both contract addresses and token ids are supported with the same method. Pass whichever identifier you have:
+Get token metadata by address or token ID.
 
 ```python
-success, data = await adapter.get_token("0x1234...")        # by address
-# or
-success, data = await adapter.get_token("usd-coin-base")    # by token id
+# By token ID
+success, data = await adapter.get_token("usd-coin-base")
+
+# By address
+success, data = await adapter.get_token("0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913")
 
 if success:
-    print(data)
-else:
-    print(f"Error: {data}")
+    print(f"Symbol: {data['symbol']}")
+    print(f"Decimals: {data['decimals']}")
+    print(f"Address: {data['address']}")
 ```
 
-### Get Token Price
+### get_token_price
+
+Get current price data for a token.
 
 ```python
-success, data = await adapter.get_token_price("token-123")
+success, data = await adapter.get_token_price("usd-coin-base")
 if success:
     print(f"Price: ${data['current_price']}")
     print(f"24h Change: {data['price_change_percentage_24h']}%")
-else:
-    print(f"Error: {data}")
 ```
 
-### Get Gas Token
+### get_gas_token
+
+Get the native gas token for a chain.
 
 ```python
 success, data = await adapter.get_gas_token("base")
 if success:
-    print(f"Gas token: {data['symbol']} - {data['name']}")
-    print(f"Address: {data['address']}")
-else:
-    print(f"Error: {data}")
+    print(f"Gas token: {data['symbol']}")
 ```
 
-## API Endpoints
-
-The adapter uses the following Wayfinder API endpoint:
-
-- `GET /api/v1/blockchain/tokens/detail/?query=...&market_data=...&chain_id=...`
+## Response Format
 
-## Error Handling
+Token metadata includes:
+- `symbol` - Token symbol (e.g., "USDC")
+- `name` - Full name
+- `address` - Contract address
+- `decimals` - Token decimals
+- `chain_id` - Chain ID
+- `token_id` - Wayfinder token identifier
 
-All methods return a tuple of `(success: bool, data: Any)` where:
-- `success` indicates whether the operation was successful
-- `data` contains either the token information (on success) or an error message (on failure)
+## Dependencies
 
-## Health Check
+- `TokenClient` - Low-level API client
 
-The adapter includes a health check that tests connectivity to the API:
+## Testing
 
-```python
-health = await adapter.health_check()
-print(f"Status: {health['status']}")
+```bash
+poetry run pytest wayfinder_paths/adapters/token_adapter/ -v
 ```
-
-## Examples
-
-See `examples.json` for more detailed usage examples.

wayfinder_paths/adapters/token_adapter/adapter.py

@@ -9,11 +9,6 @@ from wayfinder_paths.core.clients.TokenClient import (
 
 
 class TokenAdapter(BaseAdapter):
-    """
-    Token adapter that wraps the _get_token_via_api method for fetching token data
-    via HeadlessAPIViewSet endpoints. Supports both address and token_id lookups.
-    """
-
     adapter_type: str = "TOKEN"
 
     def __init__(
@@ -27,15 +22,6 @@ class TokenAdapter(BaseAdapter):
     async def get_token(
         self, query: str, *, chain_id: int | None = None
     ) -> tuple[bool, TokenDetails | str]:
-        """
-        Get token data by address using the token-details endpoint.
-
-        Args:
-            address: Token contract address
-
-        Returns:
-            Tuple of (success, data) where data is the token information or error message
-        """
         try:
             data = await self.token_client.get_token_details(query, chain_id=chain_id)
             if not data:
@@ -48,15 +34,6 @@ class TokenAdapter(BaseAdapter):
     async def get_token_price(
         self, token_id: str, *, chain_id: int | None = None
     ) -> tuple[bool, dict[str, Any] | str]:
-        """
-        Get token price by token ID or address using the token-details endpoint.
-
-        Args:
-            token_id: Token identifier or address
-
-        Returns:
-            Tuple of (success, data) where data is the price information or error message
-        """
         try:
             data = await self.token_client.get_token_details(
                 token_id, market_data=True, chain_id=chain_id
@@ -83,15 +60,6 @@ class TokenAdapter(BaseAdapter):
             return (False, str(e))
 
     async def get_gas_token(self, chain_code: str) -> tuple[bool, GasToken | str]:
-        """
-        Get gas token for a given chain code.
-
-        Args:
-            chain_code: Chain code (e.g., "base", "ethereum")
-
-        Returns:
-            Tuple of (success, data) where data is the gas token information or error message
-        """
         try:
             data = await self.token_client.get_gas_token(chain_code)
             if not data:

wayfinder_paths/adapters/token_adapter/test_adapter.py

@@ -6,21 +6,17 @@ from wayfinder_paths.adapters.token_adapter.adapter import TokenAdapter
 
 
 class TestTokenAdapter:
-    """Test cases for TokenAdapter"""
-
     @pytest.fixture
     def adapter(self):
         return TokenAdapter()
 
     def test_init_with_default_config(self):
-        """Test adapter initialization with default config"""
         adapter = TokenAdapter()
         assert adapter.adapter_type == "TOKEN"
         assert adapter.token_client is not None
 
     @pytest.mark.asyncio
     async def test_get_token_success(self, adapter):
-        """Test successful token retrieval by address"""
         mock_token_data = {
             "address": "0x1234...",
             "symbol": "TEST",
@@ -38,7 +34,6 @@ class TestTokenAdapter:
 
     @pytest.mark.asyncio
     async def test_get_token_not_found(self, adapter):
-        """Test token not found by address"""
         with patch.object(adapter.token_client, "get_token_details", return_value=None):
             success, data = await adapter.get_token("0x1234...")
 
@@ -47,7 +42,6 @@ class TestTokenAdapter:
 
     @pytest.mark.asyncio
     async def test_get_token_by_token_id(self, adapter):
-        """Test token retrieval with token_id"""
         mock_token_data = {"address": "0x1234...", "symbol": "TEST"}
 
         with patch.object(
@@ -59,12 +53,10 @@ class TestTokenAdapter:
             assert data == mock_token_data
 
     def test_adapter_type(self, adapter):
-        """Test adapter has adapter_type"""
         assert adapter.adapter_type == "TOKEN"
 
     @pytest.mark.asyncio
     async def test_get_token_price_success(self, adapter):
-        """Test successful token price retrieval"""
         mock_token_data = {
             "current_price": 1.50,
             "price_change_24h": 0.05,
@@ -85,11 +77,10 @@ class TestTokenAdapter:
             assert data["symbol"] == "TEST"
             assert data["name"] == "Test Token"
             assert data["total_volume"] == 50000
-            assert data["price_change_percentage_24h"] == 5.0  # 0.05 * 100
+            assert data["price_change_percentage_24h"] == 5.0
 
     @pytest.mark.asyncio
     async def test_get_token_price_not_found(self, adapter):
-        """Test token price not found"""
         with patch.object(adapter.token_client, "get_token_details", return_value=None):
             success, data = await adapter.get_token_price("invalid-token")
 
@@ -98,7 +89,6 @@ class TestTokenAdapter:
 
     @pytest.mark.asyncio
     async def test_get_gas_token_success(self, adapter):
-        """Test successful gas token retrieval"""
         mock_gas_token_data = {
             "id": "ethereum_0x0000000000000000000000000000000000000000",
             "token_id": "ethereum_0x0000000000000000000000000000000000000000",
@@ -119,7 +109,6 @@ class TestTokenAdapter:
 
     @pytest.mark.asyncio
     async def test_get_gas_token_not_found(self, adapter):
-        """Test gas token not found"""
         with patch.object(adapter.token_client, "get_gas_token", return_value=None):
             success, data = await adapter.get_gas_token("invalid-chain")
 

wayfinder_paths/conftest.py

@@ -1,20 +1,12 @@
-"""
-Conftest for wayfinder-paths package tests.
-Adds wayfinder-paths directory to Python path for imports.
-This must run early, so imports like 'from tests.test_utils' work.
-"""
-
 import sys
 from pathlib import Path
 
-# Add wayfinder-paths directory to Python path for imports (for tests.test_utils)
 # This needs to be at index 0 to take precedence over repo root 'tests/' directory
 _wayfinder_path_dir = Path(__file__).parent
 _wayfinder_path_str = str(_wayfinder_path_dir)
 
 
 def pytest_configure(config):
-    """Configure pytest - runs early to set up imports."""
     if _wayfinder_path_str not in sys.path:
         sys.path.insert(0, _wayfinder_path_str)
     elif sys.path.index(_wayfinder_path_str) > 0:

wayfinder_paths/core/__init__.py

@@ -1,5 +1,3 @@
-"""Wayfinder Paths Core Engine"""
-
 from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
 from wayfinder_paths.core.engine.StrategyJob import StrategyJob
 from wayfinder_paths.core.strategies.Strategy import (

wayfinder_paths/core/adapters/BaseAdapter.py

@@ -7,8 +7,6 @@ from loguru import logger
 
 
 class BaseAdapter(ABC):
-    """Base adapter class for exchange/protocol integrations"""
-
     adapter_type: str | None = None
 
     def __init__(self, name: str, config: dict[str, Any] | None = None):
@@ -17,24 +15,9 @@ class BaseAdapter(ABC):
         self.logger = logger.bind(adapter=self.__class__.__name__)
 
     async def connect(self) -> bool:
-        """Optional: establish connectivity. Defaults to True."""
         return True
 
     async def get_balance(self, asset: str) -> dict[str, Any]:
-        """
-        Get balance for an asset.
-        Optional method that can be overridden by subclasses.
-
-        Args:
-            asset: Asset identifier (token address, token ID, etc.).
-
-        Returns:
-            Dictionary containing balance information.
-
-        Raises:
-            ValueError: If asset is empty or invalid.
-            NotImplementedError: If this adapter does not support balance queries.
-        """
         if not asset or not isinstance(asset, str) or not asset.strip():
             raise ValueError("asset must be a non-empty string")
         raise NotImplementedError(
@@ -42,10 +25,6 @@ class BaseAdapter(ABC):
         )
 
     async def health_check(self) -> dict[str, Any]:
-        """
-        Check adapter health and connectivity
-        Returns: Health status dictionary
-        """
         try:
             connected = await self.connect()
             return {
@@ -61,5 +40,4 @@ class BaseAdapter(ABC):
             }
 
     async def close(self) -> None:
-        """Clean up resources"""
         pass

wayfinder_paths/core/adapters/__init__.py

@@ -1,5 +0,0 @@
-"""Core Adapter Module - SDK surface re-export"""
-
-from .base import BaseAdapter
-
-__all__ = ["BaseAdapter"]

wayfinder_paths/core/adapters/models.py

@@ -1,5 +1,3 @@
-"""Pydantic models for ledger operations."""
-
 from typing import Annotated, Any, Literal
 
 from pydantic import BaseModel, Field
@@ -12,8 +10,6 @@ class OperationBase(BaseModel):
 
 
 class SWAP(OperationBase):
-    """Swap operation."""
-
     type: Literal["SWAP"] = "SWAP"
     from_token_id: str
     to_token_id: str
@@ -38,7 +34,6 @@ class UNLEND(OperationBase):
 
 
 # Type alias for operation types (currently only SWAP is used)
-# Add more operation types here as needed
 Operation = SWAP | LEND | UNLEND
 
 

wayfinder_paths/core/analytics/__init__.py

@@ -1,5 +1,3 @@
-"""Reusable, strategy-agnostic analytics helpers."""
-
 from .bootstrap import block_bootstrap_paths
 from .stats import percentile, rolling_min_sum, z_from_conf
 

wayfinder_paths/core/analytics/bootstrap.py

@@ -10,22 +10,6 @@ def block_bootstrap_paths(
     sims: int,
     rng: random.Random,
 ) -> list[tuple[list[float], ...]]:
-    """
-    Block-bootstrap aligned series together.
-
-    Samples contiguous blocks from the same indices across every series so their
-    time alignment is preserved (useful for resampling correlated paths).
-
-    Args:
-        *series: One or more equal-frequency series (funding, closes, highs, ...)
-        block_hours: Block length for sampling (clamped to [1, base_len])
-        sims: Number of bootstrap paths to return
-        rng: Random generator
-
-    Returns:
-        List of tuples, each containing resampled series lists (truncated to the
-        shared base length).
-    """
     if sims <= 0 or not series:
         return []
 

wayfinder_paths/core/analytics/stats.py

@@ -6,12 +6,10 @@ from statistics import NormalDist
 
 
 def z_from_conf(confidence: float) -> float:
-    """Return the two-sided z-score for a confidence level (e.g. 0.975)."""
     return NormalDist().inv_cdf((1 + float(confidence)) / 2)
 
 
 def rolling_min_sum(arr: Sequence[float], window: int) -> float:
-    """Return the minimum rolling window sum over `arr`."""
     values = list(arr)
     if window <= 0:
         return 0.0
@@ -27,11 +25,6 @@ def rolling_min_sum(arr: Sequence[float], window: int) -> float:
 
 
 def percentile(sorted_values: Sequence[float], pct: float) -> float:
-    """
-    Inclusive percentile on a pre-sorted list.
-
-    Mirrors a simple linear interpolation between closest ranks.
-    """
     values = list(sorted_values)
     if not values:
         return float("nan")

wayfinder_paths/core/analytics/test_analytics.py

@@ -1,5 +1,3 @@
-"""Tests for core analytics modules (bootstrap, stats)."""
-
 import math
 import random
 
@@ -12,29 +10,23 @@ from wayfinder_paths.core.analytics.stats import (
 
 
 class TestBlockBootstrapPaths:
-    """Tests for block_bootstrap_paths function."""
-
     def test_returns_empty_when_sims_zero(self):
-        """Should return empty list when sims=0."""
         result = block_bootstrap_paths(
             [1.0, 2.0, 3.0], block_hours=2, sims=0, rng=random.Random(42)
         )
         assert result == []
 
     def test_returns_empty_when_series_empty(self):
-        """Should return empty list when no series provided."""
         result = block_bootstrap_paths(block_hours=2, sims=10, rng=random.Random(42))
         assert result == []
 
     def test_returns_empty_when_base_len_one(self):
-        """Should return empty list when series has only one element."""
         result = block_bootstrap_paths(
             [1.0], block_hours=2, sims=10, rng=random.Random(42)
         )
         assert result == []
 
     def test_single_series(self):
-        """Should bootstrap a single series correctly."""
         series = [1.0, 2.0, 3.0, 4.0, 5.0]
         result = block_bootstrap_paths(
             series, block_hours=2, sims=5, rng=random.Random(42)
@@ -42,11 +34,10 @@ class TestBlockBootstrapPaths:
 
         assert len(result) == 5
         for path in result:
-            assert len(path) == 1  # One series
-            assert len(path[0]) == 5  # Same length as original
+            assert len(path) == 1
+            assert len(path[0]) == 5
 
     def test_multiple_aligned_series(self):
-        """Should bootstrap multiple series with aligned indices."""
         series_a = [1.0, 2.0, 3.0, 4.0, 5.0]
         series_b = [10.0, 20.0, 30.0, 40.0, 50.0]
         result = block_bootstrap_paths(
@@ -55,12 +46,11 @@ class TestBlockBootstrapPaths:
 
         assert len(result) == 3
         for path in result:
-            assert len(path) == 2  # Two series
+            assert len(path) == 2
             assert len(path[0]) == 5
             assert len(path[1]) == 5
 
     def test_preserves_length(self):
-        """Bootstrapped paths should have same length as input."""
         series = list(range(100))
         series_float = [float(x) for x in series]
         result = block_bootstrap_paths(
@@ -71,7 +61,6 @@ class TestBlockBootstrapPaths:
             assert len(path[0]) == 100
 
     def test_block_clamping(self):
-        """Block hours should be clamped to valid range."""
         series = [1.0, 2.0, 3.0]
 
         # Block larger than series - should still work
@@ -88,48 +77,37 @@ class TestBlockBootstrapPaths:
 
 
 class TestZFromConf:
-    """Tests for z_from_conf function."""
-
     def test_95_confidence(self):
-        """95% confidence should give z ≈ 1.96."""
         z = z_from_conf(0.95)
         assert 1.95 < z < 1.97
 
     def test_99_confidence(self):
-        """99% confidence should give z ≈ 2.576."""
         z = z_from_conf(0.99)
         assert 2.57 < z < 2.58
 
     def test_90_confidence(self):
-        """90% confidence should give z ≈ 1.645."""
         z = z_from_conf(0.90)
         assert 1.64 < z < 1.66
 
 
 class TestRollingMinSum:
-    """Tests for rolling_min_sum function."""
-
     def test_basic(self):
-        """Basic rolling min sum calculation."""
         arr = [1, -2, 3, -4, 5]
         result = rolling_min_sum(arr, 2)
         # Windows: [1,-2]=-1, [-2,3]=1, [3,-4]=-1, [-4,5]=1
         assert result == -1
 
     def test_window_larger_than_arr(self):
-        """Window larger than array returns sum of array."""
         arr = [1.0, 2.0, 3.0]
         result = rolling_min_sum(arr, 10)
         assert result == 6.0
 
     def test_window_zero(self):
-        """Window of zero returns 0."""
         arr = [1.0, 2.0, 3.0]
         result = rolling_min_sum(arr, 0)
         assert result == 0.0
 
     def test_all_negative(self):
-        """All negative values."""
         arr = [-1.0, -2.0, -3.0, -4.0]
         result = rolling_min_sum(arr, 2)
         # Windows: [-1,-2]=-3, [-2,-3]=-5, [-3,-4]=-7
@@ -137,34 +115,27 @@ class TestRollingMinSum:
 
 
 class TestPercentile:
-    """Tests for percentile function."""
-
     def test_empty_returns_nan(self):
-        """Empty list returns nan."""
         result = percentile([], 0.5)
         assert math.isnan(result)
 
     def test_single_value(self):
-        """Single value returns that value regardless of percentile."""
         assert percentile([42.0], 0.0) == 42.0
         assert percentile([42.0], 0.5) == 42.0
         assert percentile([42.0], 1.0) == 42.0
 
     def test_median(self):
-        """50th percentile (median) calculation."""
         sorted_values = [1.0, 2.0, 3.0, 4.0, 5.0]
         result = percentile(sorted_values, 0.5)
         assert result == 3.0
 
     def test_interpolation(self):
-        """Percentile with interpolation."""
         sorted_values = [0.0, 10.0]
         # 25th percentile should interpolate to 2.5
         result = percentile(sorted_values, 0.25)
         assert result == 2.5
 
     def test_bounds_clamped(self):
-        """Percentile values outside [0,1] are clamped."""
         sorted_values = [1.0, 2.0, 3.0]
-        assert percentile(sorted_values, -1.0) == 1.0  # Clamped to 0
-        assert percentile(sorted_values, 2.0) == 3.0  # Clamped to 1
+        assert percentile(sorted_values, -1.0) == 1.0
+        assert percentile(sorted_values, 2.0) == 3.0

wayfinder_paths/core/clients/BRAPClient.py

@@ -1,8 +1,3 @@
-"""
-BRAP (Bridge/Router/Adapter Protocol) Client
-Provides access to quote operations via the blockchain quote endpoint.
-"""
-
 from __future__ import annotations
 
 import time
@@ -15,8 +10,6 @@ from wayfinder_paths.core.config import get_api_base_url
 
 
 class QuoteTx(TypedDict, total=False):
-    """Quote transaction data structure"""
-
     data: str
     to: str
     value: str
@@ -24,8 +17,6 @@ class QuoteTx(TypedDict, total=False):
 
 
 class QuoteData(TypedDict):
-    """Quote data structure"""
-
     gas: Required[str]
     amountOut: Required[str]
     priceImpact: Required[int]
@@ -37,8 +28,6 @@ class QuoteData(TypedDict):
 
 
 class FeeBreakdown(TypedDict):
-    """Fee breakdown structure"""
-
     name: Required[str]
     amount: Required[int]
     amount_usd: Required[float]
@@ -47,15 +36,11 @@ class FeeBreakdown(TypedDict):
 
 
 class FeeEstimate(TypedDict):
-    """Fee estimate structure"""
-
     fee_total_usd: Required[float]
     fee_breakdown: Required[list[FeeBreakdown]]
 
 
 class Calldata(TypedDict, total=False):
-    """Calldata structure"""
-
     data: str
     to: str
     value: str
@@ -63,8 +48,6 @@ class Calldata(TypedDict, total=False):
 
 
 class BRAPQuoteEntry(TypedDict):
-    """BRAP quote entry structure"""
-
     provider: Required[str]
     quote: Required[QuoteData]
     calldata: Required[Calldata]
@@ -82,15 +65,11 @@ class BRAPQuoteEntry(TypedDict):
 
 
 class BRAPQuoteResponse(TypedDict):
-    """BRAP quote response structure"""
-
     quotes: Required[list[BRAPQuoteEntry]]
     best_quote: Required[BRAPQuoteEntry]
 
 
 class BRAPClient(WayfinderClient):
-    """Client for BRAP quote operations"""
-
     def __init__(self):
         super().__init__()
         self.api_base_url = f"{get_api_base_url()}/v1/blockchain/braps"
@@ -105,20 +84,6 @@ class BRAPClient(WayfinderClient):
         from_wallet: str,
         from_amount: str,
     ) -> BRAPQuoteResponse:  # type: ignore # noqa: E501
-        """
-        Get a quote for a bridge/swap operation.
-
-        Args:
-            from_token: Source token contract address
-            to_token: Destination token contract address
-            from_chain: Source chain ID
-            to_chain: Destination chain ID
-            from_wallet: Source wallet address
-            from_amount: Amount to swap (in smallest units)
-
-        Returns:
-            Quote response including quotes array and best_quote
-        """
         logger.info(
             f"Getting BRAP quote: {from_token} -> {to_token} (chain {from_chain} -> {to_chain})"
         )