wayfinder-paths 0.1.4__py3-none-any.whl → 0.1.5__py3-none-any.whl

wayfinder_paths/adapters/pool_adapter/adapter.py

@@ -1,7 +1,12 @@
 from typing import Any
 
 from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
-from wayfinder_paths.core.clients.PoolClient import PoolClient
+from wayfinder_paths.core.clients.PoolClient import (
+    LlamaMatch,
+    LlamaReport,
+    PoolClient,
+    PoolList,
+)
 
 
 class PoolAdapter(BaseAdapter):
@@ -27,7 +32,7 @@ class PoolAdapter(BaseAdapter):
 
     async def get_pools_by_ids(
         self, pool_ids: list[str], merge_external: bool | None = None
-    ) -> tuple[bool, Any]:
+    ) -> tuple[bool, PoolList | str]:
         """
         Get pool information by pool IDs.
 
@@ -50,7 +55,7 @@ class PoolAdapter(BaseAdapter):
 
     async def get_all_pools(
         self, merge_external: bool | None = None
-    ) -> tuple[bool, Any]:
+    ) -> tuple[bool, PoolList | str]:
         """
         Get all available pools.
 
@@ -67,21 +72,7 @@ class PoolAdapter(BaseAdapter):
             self.logger.error(f"Error fetching all pools: {e}")
             return (False, str(e))
 
-    async def get_combined_pool_reports(self) -> tuple[bool, Any]:
-        """
-        Get combined pool reports with analytics.
-
-        Returns:
-            Tuple of (success, data) where data is combined reports or error message
-        """
-        try:
-            data = await self.pool_client.get_combined_pool_reports()
-            return (True, data)
-        except Exception as e:
-            self.logger.error(f"Error fetching combined pool reports: {e}")
-            return (False, str(e))
-
-    async def get_llama_matches(self) -> tuple[bool, Any]:
+    async def get_llama_matches(self) -> tuple[bool, dict[str, LlamaMatch] | str]:
         """
         Get Llama protocol matches for pools.
 
@@ -95,7 +86,9 @@ class PoolAdapter(BaseAdapter):
             self.logger.error(f"Error fetching Llama matches: {e}")
             return (False, str(e))
 
-    async def get_llama_reports(self, identifiers: list[str]) -> tuple[bool, Any]:
+    async def get_llama_reports(
+        self, identifiers: list[str]
+    ) -> tuple[bool, dict[str, LlamaReport] | str]:
         """
         Get Llama reports for specific identifiers.
 

wayfinder_paths/adapters/token_adapter/adapter.py

@@ -1,7 +1,11 @@
 from typing import Any
 
 from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
-from wayfinder_paths.core.clients.TokenClient import TokenClient
+from wayfinder_paths.core.clients.TokenClient import (
+    GasToken,
+    TokenClient,
+    TokenDetails,
+)
 
 
 class TokenAdapter(BaseAdapter):
@@ -20,7 +24,7 @@ class TokenAdapter(BaseAdapter):
         super().__init__("token_adapter", config)
         self.token_client = token_client or TokenClient()
 
-    async def get_token(self, query: str) -> tuple[bool, Any]:
+    async def get_token(self, query: str) -> tuple[bool, TokenDetails | str]:
         """
         Get token data by address using the token-details endpoint.
 
@@ -39,7 +43,7 @@ class TokenAdapter(BaseAdapter):
             self.logger.error(f"Error getting token by query {query}: {e}")
             return (False, str(e))
 
-    async def get_token_price(self, token_id: str) -> tuple[bool, Any]:
+    async def get_token_price(self, token_id: str) -> tuple[bool, dict[str, Any] | str]:
         """
         Get token price by token ID or address using the token-details endpoint.
 
@@ -72,7 +76,7 @@ class TokenAdapter(BaseAdapter):
             self.logger.error(f"Error getting token price for {token_id}: {e}")
             return (False, str(e))
 
-    async def get_gas_token(self, chain_code: str) -> tuple[bool, Any]:
+    async def get_gas_token(self, chain_code: str) -> tuple[bool, GasToken | str]:
         """
         Get gas token for a given chain code.
 

wayfinder_paths/core/__init__.py

@@ -1,7 +1,7 @@
-"""Wayfinder Vaults Core Engine"""
+"""Wayfinder Paths Core Engine"""
 
 from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
-from wayfinder_paths.core.engine.VaultJob import VaultJob
+from wayfinder_paths.core.engine.StrategyJob import StrategyJob
 from wayfinder_paths.core.strategies.Strategy import StatusDict, StatusTuple, Strategy
 
 __all__ = [
@@ -9,5 +9,5 @@ __all__ = [
     "StatusDict",
     "StatusTuple",
     "BaseAdapter",
-    "VaultJob",
+    "StrategyJob",
 ]

wayfinder_paths/core/adapters/BaseAdapter.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from abc import ABC
 from typing import Any
 
@@ -7,7 +9,7 @@ from loguru import logger
 class BaseAdapter(ABC):
     """Base adapter class for exchange/protocol integrations"""
 
-    adapter_type: str = None
+    adapter_type: str | None = None
 
     def __init__(self, name: str, config: dict[str, Any] | None = None):
         self.name = name
@@ -19,7 +21,22 @@ class BaseAdapter(ABC):
         return True
 
     async def get_balance(self, asset: str) -> dict[str, Any]:
-        """Optional: provide balance. Default is not implemented."""
+        """
+        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(
             f"get_balance not supported by {self.__class__.__name__}"
         )
@@ -43,6 +60,6 @@ class BaseAdapter(ABC):
                 "adapter": self.adapter_type or self.__class__.__name__,
             }
 
-    async def close(self):
+    async def close(self) -> None:
         """Clean up resources"""
         pass

wayfinder_paths/core/adapters/models.py

@@ -0,0 +1,41 @@
+"""Pydantic models for ledger operations."""
+
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class SWAP(BaseModel):
+    """Swap operation."""
+
+    type: Literal["SWAP"] = "SWAP"
+    from_token_id: str
+    to_token_id: str
+    from_amount: str
+    to_amount: str
+    from_amount_usd: float
+    to_amount_usd: float
+    transaction_hash: str | None = None
+    transaction_status: str | None = None
+    transaction_receipt: dict[str, Any] | None = None
+
+
+class LEND(BaseModel):
+    type: Literal["LEND"] = "LEND"
+    contract: str
+    amount: int
+
+
+class UNLEND(BaseModel):
+    type: Literal["UNLEND"] = "UNLEND"
+    contract: str
+    amount: int
+
+
+# Type alias for operation types (currently only SWAP is used)
+# Add more operation types here as needed
+Operation = SWAP | LEND | UNLEND
+
+
+class STRAT_OP(BaseModel):
+    op_data: Annotated[Operation, Field(discriminator="type")]

wayfinder_paths/core/clients/BRAPClient.py

@@ -3,8 +3,10 @@ BRAP (Bridge/Router/Adapter Protocol) Client
 Provides access to quote operations via the public quote endpoint.
 """
 
+from __future__ import annotations
+
 import time
-from typing import Any
+from typing import Any, NotRequired, Required, TypedDict
 
 from loguru import logger
 
@@ -13,6 +15,23 @@ from wayfinder_paths.core.clients.WayfinderClient import WayfinderClient
 from wayfinder_paths.core.settings import settings
 
 
+class BRAPQuote(TypedDict):
+    """BRAP quote response structure"""
+
+    from_token_address: Required[str]
+    to_token_address: Required[str]
+    from_chain_id: Required[int]
+    to_chain_id: Required[int]
+    from_address: Required[str]
+    to_address: Required[str]
+    amount1: Required[str]
+    amount2: NotRequired[str]
+    routes: NotRequired[list[dict[str, Any]]]
+    fees: NotRequired[dict[str, Any] | None]
+    slippage: NotRequired[float | None]
+    wayfinder_fee: NotRequired[float | None]
+
+
 class BRAPClient(WayfinderClient):
     """Client for BRAP quote operations"""
 
@@ -33,7 +52,7 @@ class BRAPClient(WayfinderClient):
         amount1: str,
         slippage: float | None = None,
         wayfinder_fee: float | None = None,
-    ) -> dict[str, Any]:
+    ) -> BRAPQuote:
         """
         Get a quote for a bridge/swap operation.
 

wayfinder_paths/core/clients/ClientManager.py

@@ -28,7 +28,7 @@ from wayfinder_paths.core.clients.WalletClient import WalletClient
 
 class ClientManager:
     """
-    Manages all API client instances for a vault job.
+    Manages all API client instances for a strategy job.
 
     Args:
         clients: Optional dict of pre-instantiated clients to inject directly.
@@ -66,6 +66,33 @@ class ClientManager:
         self._brap_client: BRAPClientProtocol | None = None
         self._simulation_client: SimulationClientProtocol | None = None
 
+    def _get_or_create_client(
+        self,
+        client_attr: str,
+        injected_key: str,
+        client_class: type[Any],
+    ) -> Any:
+        """
+        Helper method to get or create a client instance.
+
+        Args:
+            client_attr: Name of the private attribute storing the client (e.g., "_token_client").
+            injected_key: Key to look up in _injected_clients dict.
+            client_class: Client class to instantiate if not injected.
+
+        Returns:
+            Client instance.
+        """
+        client = getattr(self, client_attr)
+        if not client:
+            client = self._injected_clients.get(injected_key) or client_class(
+                api_key=self._api_key
+            )
+            setattr(self, client_attr, client)
+            if self._access_token and hasattr(client, "set_bearer_token"):
+                client.set_bearer_token(self._access_token)
+        return client
+
     @property
     def auth(self) -> AuthClient | None:
         """Get or create auth client. Returns None if skip_auth=True."""
@@ -80,96 +107,48 @@ class ClientManager:
     @property
     def token(self) -> TokenClientProtocol:
         """Get or create token client"""
-        if not self._token_client:
-            self._token_client = self._injected_clients.get("token") or TokenClient(
-                api_key=self._api_key
-            )
-            if self._access_token and hasattr(self._token_client, "set_bearer_token"):
-                self._token_client.set_bearer_token(self._access_token)
-        return self._token_client
+        return self._get_or_create_client("_token_client", "token", TokenClient)
 
     @property
     def transaction(self) -> TransactionClientProtocol:
         """Get or create transaction client"""
-        if not self._transaction_client:
-            self._transaction_client = self._injected_clients.get(
-                "transaction"
-            ) or TransactionClient(api_key=self._api_key)
-            if self._access_token and hasattr(
-                self._transaction_client, "set_bearer_token"
-            ):
-                self._transaction_client.set_bearer_token(self._access_token)
-        return self._transaction_client
+        return self._get_or_create_client(
+            "_transaction_client", "transaction", TransactionClient
+        )
 
     @property
     def ledger(self) -> LedgerClientProtocol:
         """Get or create ledger client"""
-        if not self._ledger_client:
-            self._ledger_client = self._injected_clients.get("ledger") or LedgerClient(
-                api_key=self._api_key
-            )
-            if self._access_token and hasattr(self._ledger_client, "set_bearer_token"):
-                self._ledger_client.set_bearer_token(self._access_token)
-        return self._ledger_client
+        return self._get_or_create_client("_ledger_client", "ledger", LedgerClient)
 
     @property
     def pool(self) -> PoolClientProtocol:
         """Get or create pool client"""
-        if not self._pool_client:
-            self._pool_client = self._injected_clients.get("pool") or PoolClient(
-                api_key=self._api_key
-            )
-            if self._access_token and hasattr(self._pool_client, "set_bearer_token"):
-                self._pool_client.set_bearer_token(self._access_token)
-        return self._pool_client
+        return self._get_or_create_client("_pool_client", "pool", PoolClient)
 
     @property
     def hyperlend(self) -> HyperlendClientProtocol:
         """Get or create hyperlend client"""
-        if not self._hyperlend_client:
-            self._hyperlend_client = self._injected_clients.get(
-                "hyperlend"
-            ) or HyperlendClient(api_key=self._api_key)
-            if self._access_token and hasattr(
-                self._hyperlend_client, "set_bearer_token"
-            ):
-                self._hyperlend_client.set_bearer_token(self._access_token)
-        return self._hyperlend_client
+        return self._get_or_create_client(
+            "_hyperlend_client", "hyperlend", HyperlendClient
+        )
 
     @property
     def wallet(self) -> WalletClientProtocol:
         """Get or create wallet client"""
-        if not self._wallet_client:
-            self._wallet_client = self._injected_clients.get("wallet") or WalletClient(
-                api_key=self._api_key
-            )
-            if self._access_token and hasattr(self._wallet_client, "set_bearer_token"):
-                self._wallet_client.set_bearer_token(self._access_token)
-        return self._wallet_client
+        return self._get_or_create_client("_wallet_client", "wallet", WalletClient)
 
     @property
     def brap(self) -> BRAPClientProtocol:
         """Get or create BRAP client"""
-        if not self._brap_client:
-            self._brap_client = self._injected_clients.get("brap") or BRAPClient(
-                api_key=self._api_key
-            )
-            if self._access_token and hasattr(self._brap_client, "set_bearer_token"):
-                self._brap_client.set_bearer_token(self._access_token)
-        return self._brap_client
+        return self._get_or_create_client("_brap_client", "brap", BRAPClient)
 
     @property
     def simulation(self) -> SimulationClientProtocol:
         """Get or create simulation client"""
-        if not self._simulation_client:
-            self._simulation_client = self._injected_clients.get(
-                "simulation"
-            ) or SimulationClient(api_key=self._api_key)
-            if self._access_token and hasattr(
-                self._simulation_client, "set_bearer_token"
-            ):
-                self._simulation_client.set_bearer_token(self._access_token)
-        return self._simulation_client
+        return self._get_or_create_client(
+            "_simulation_client", "simulation", SimulationClient
+        )
 
     async def authenticate(
         self,

wayfinder_paths/core/clients/HyperlendClient.py

@@ -3,12 +3,53 @@ Hyperlend Client
 Provides access to Hyperlend stable markets data via public endpoints.
 """
 
-from typing import Any
+from __future__ import annotations
+
+from typing import Any, NotRequired, Required, TypedDict
 
 from wayfinder_paths.core.clients.WayfinderClient import WayfinderClient
 from wayfinder_paths.core.settings import settings
 
 
+class StableMarket(TypedDict):
+    """Stable market data structure"""
+
+    chain_id: Required[int]
+    token_address: Required[str]
+    symbol: Required[str]
+    name: Required[str]
+    underlying_tokens: Required[float]
+    buffer_bps: Required[int]
+    min_buffer_tokens: Required[float]
+    is_stable_symbol: Required[bool]
+
+
+class AssetsView(TypedDict):
+    """Assets view response structure"""
+
+    chain_id: Required[int]
+    user_address: Required[str]
+    assets: Required[list[dict[str, Any]]]
+    total_value: NotRequired[float | None]
+
+
+class MarketEntry(TypedDict):
+    """Market entry data structure"""
+
+    chain_id: Required[int]
+    token_address: Required[str]
+    market_data: Required[dict[str, Any]]
+
+
+class LendRateHistory(TypedDict):
+    """Lend rate history response structure"""
+
+    chain_id: Required[int]
+    token_address: Required[str]
+    lookback_hours: Required[int]
+    rates: Required[list[dict[str, Any]]]
+
+
 class HyperlendClient(WayfinderClient):
     """Client for Hyperlend-related operations"""
 
@@ -24,7 +65,7 @@ class HyperlendClient(WayfinderClient):
         buffer_bps: int | None = None,
         min_buffer_tokens: float | None = None,
         is_stable_symbol: bool | None = None,
-    ) -> dict[str, Any]:
+    ) -> list[StableMarket]:
         """
         Fetch stable markets from Hyperlend.
 
@@ -62,7 +103,7 @@ class HyperlendClient(WayfinderClient):
         *,
         chain_id: int,
         user_address: str,
-    ) -> dict[str, Any]:
+    ) -> AssetsView:
         """
         Fetch assets view for a user address from Hyperlend.
 
@@ -92,7 +133,7 @@ class HyperlendClient(WayfinderClient):
         *,
         chain_id: int,
         token_address: str,
-    ) -> dict[str, Any]:
+    ) -> MarketEntry:
         """
         Fetch market entry from Hyperlend.
 
@@ -123,7 +164,7 @@ class HyperlendClient(WayfinderClient):
         chain_id: int,
         token_address: str,
         lookback_hours: int,
-    ) -> dict[str, Any]:
+    ) -> LendRateHistory:
         """
         Fetch lend rate history from Hyperlend.