feat: v0.2.0 — use canonical field names with backwards compat

Rename EVOpportunity model fields to match canonical API names:
- ev_percent → ev_percentage
- true_probability → fair_probability
- devig_book → sharp_book
- kelly_fraction → kelly_percent

Uses Pydantic AliasChoices so the SDK accepts both old and new field
names from API responses, maintaining full backwards compatibility.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Mlaz-code

README.md

@@ -27,9 +27,9 @@ for arb in arbs.data:
 # --- +EV opportunities ---
 evs = client.ev.get(min_ev=3.0, sport="basketball")
 for opp in evs.data:
-    print(f"+{opp.ev_percent:.1f}% EV on {opp.selection} @ {opp.sportsbook}")
-    if opp.kelly_fraction:
-        print(f"  Kelly: {opp.kelly_fraction:.1%} of bankroll")
+    print(f"+{opp.ev_percentage:.1f}% EV on {opp.selection} @ {opp.sportsbook}")
+    if opp.kelly_percent:
+        print(f"  Kelly: {opp.kelly_percent:.1%} of bankroll")
 
 # --- Best odds across books ---
 odds = client.odds.best(league="nba", market="moneyline")
@@ -47,7 +47,7 @@ stream = client.stream.opportunities(league="nba")
 @stream.on("ev:detected")
 def on_ev(data):
     for opp in data:
-        print(f"+EV: {opp['selection']} {opp['ev_percent']}% @ {opp['sportsbook']}")
+        print(f"+EV: {opp['selection']} {opp['ev_percentage']}% @ {opp['sportsbook']}")
 
 @stream.on("arb:detected")
 def on_arb(data):

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sharpapi"
-version = "0.1.0"
+version = "0.2.0"
 description = "Official Python SDK for the SharpAPI real-time sports betting odds API"
 readme = "README.md"
 license = "MIT"
@@ -56,3 +56,5 @@ testpaths = ["tests"]
 [tool.pyright]
 pythonVersion = "3.9"
 typeCheckingMode = "standard"
+venvPath = "."
+venv = ".venv"

src/sharpapi/__init__.py

@@ -14,7 +14,7 @@
     # +EV opportunities
     evs = client.ev.get(min_ev=3.0, league="nba")
     for opp in evs.data:
-        print(f"+{opp.ev_percent}% on {opp.selection} @ {opp.sportsbook}")
+        print(f"+{opp.ev_percentage}% on {opp.selection} @ {opp.sportsbook}")
 """
 
 from .async_client import AsyncSharpAPI
@@ -51,7 +51,7 @@
 from .streaming import EventStream
 from ._utils import american_to_decimal, american_to_probability, decimal_to_american
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 __all__ = [
     # Clients

src/sharpapi/_base.py

@@ -2,8 +2,6 @@
 
 from __future__ import annotations
 
-from typing import Any
-
 import httpx
 
 from .exceptions import (
@@ -17,7 +15,7 @@
 
 DEFAULT_BASE_URL = "https://api.sharpapi.io"
 DEFAULT_TIMEOUT = 30.0
-USER_AGENT = "sharpapi-python/0.1.0"
+USER_AGENT = "sharpapi-python/0.2.0"
 
 
 def parse_response(raw: dict, model_class: type) -> APIResponse:

src/sharpapi/client.py

@@ -52,7 +52,7 @@ class SharpAPI:
         # Get +EV opportunities
         evs = client.ev.get(min_ev=3.0, league="nba")
         for opp in evs.data:
-            print(f"+{opp.ev_percent}% on {opp.selection} @ {opp.sportsbook}")
+            print(f"+{opp.ev_percentage}% on {opp.selection} @ {opp.sportsbook}")
 
         # Stream real-time updates
         stream = client.stream.opportunities(league="nba")

src/sharpapi/models.py

@@ -4,7 +4,7 @@
 
 from typing import Any, Generic, List, Optional, TypeVar
 
-from pydantic import BaseModel, Field
+from pydantic import AliasChoices, BaseModel, Field
 
 T = TypeVar("T")
 
@@ -171,14 +171,22 @@ class EVOpportunity(BaseModel):
     odds_american: int | float
     odds_decimal: float
     no_vig_odds: Optional[float] = None
-    true_probability: Optional[float] = None
-    ev_percent: float = Field(alias="ev_percent")
-    kelly_fraction: Optional[float] = None
+    fair_probability: Optional[float] = Field(
+        None, validation_alias=AliasChoices("fair_probability", "true_probability")
+    )
+    ev_percentage: float = Field(
+        validation_alias=AliasChoices("ev_percentage", "ev_percent")
+    )
+    kelly_percent: Optional[float] = Field(
+        None, validation_alias=AliasChoices("kelly_percent", "kelly_fraction")
+    )
     confidence_score: Optional[float] = None
     book_count: Optional[int] = None
     market_width: Optional[float] = None
     devig_method: Optional[str] = None
-    devig_book: Optional[str] = None
+    sharp_book: Optional[str] = Field(
+        None, validation_alias=AliasChoices("sharp_book", "devig_book")
+    )
     sharp_odds_american: Optional[int | float] = None
     sharp_odds_decimal: Optional[float] = None
     line: Optional[float] = None

tests/conftest.py

@@ -91,13 +91,17 @@
             "odds_american": -105,
             "odds_decimal": 1.952,
             "no_vig_odds": 1.912,
+            "fair_probability": 0.523,
             "true_probability": 0.523,
+            "ev_percentage": 4.2,
             "ev_percent": 4.2,
+            "kelly_percent": 0.021,
             "kelly_fraction": 0.021,
             "confidence_score": 87,
             "book_count": 8,
             "market_width": 0.043,
             "devig_method": "power",
+            "sharp_book": "pinnacle",
             "devig_book": "pinnacle",
             "is_live": False,
             "possibly_stale": False,

tests/test_async_client.py

@@ -174,7 +174,7 @@ async def test_get_ev(self):
             result = await client.ev.get(min_ev=3.0)
             assert len(result.data) == 1
             assert isinstance(result.data[0], EVOpportunity)
-            assert result.data[0].ev_percent == 4.2
+            assert result.data[0].ev_percentage == 4.2
 
 
 # =============================================================================

tests/test_client.py

@@ -260,8 +260,8 @@ def test_get_ev(self):
             assert len(result.data) == 1
             ev = result.data[0]
             assert isinstance(ev, EVOpportunity)
-            assert ev.ev_percent == 4.2
-            assert ev.kelly_fraction == 0.021
+            assert ev.ev_percentage == 4.2
+            assert ev.kelly_percent == 0.021
 
 
 class TestMiddlesResource:

tests/test_dataframe.py

@@ -22,7 +22,7 @@ def test_ev_dataframe(self):
         result = parse_response(EV_RESPONSE, EVOpportunity)
         df = result.to_dataframe()
         assert len(df) == 1
-        assert df.iloc[0]["ev_percent"] == 4.2
+        assert df.iloc[0]["ev_percentage"] == 4.2
         assert df.iloc[0]["sportsbook"] == "draftkings"
 
     def test_flattens_nested_dicts(self):
@@ -60,24 +60,24 @@ def test_multiple_rows(self):
                     "id": "ev_1", "sport": "basketball", "league": "nba",
                     "selection": "A", "sportsbook": "dk",
                     "odds_american": -110, "odds_decimal": 1.909,
-                    "ev_percent": 4.2, "possibly_stale": False, "warnings": [],
+                    "ev_percentage": 4.2, "possibly_stale": False, "warnings": [],
                 },
                 {
                     "id": "ev_2", "sport": "basketball", "league": "nba",
                     "selection": "B", "sportsbook": "fd",
                     "odds_american": 130, "odds_decimal": 2.3,
-                    "ev_percent": 2.8, "possibly_stale": False, "warnings": [],
+                    "ev_percentage": 2.8, "possibly_stale": False, "warnings": [],
                 },
             ],
         }
         result = parse_response(multi, EVOpportunity)
         df = result.to_dataframe()
         assert len(df) == 2
-        assert list(df["ev_percent"]) == [4.2, 2.8]
+        assert list(df["ev_percentage"]) == [4.2, 2.8]
         assert list(df["sportsbook"]) == ["dk", "fd"]
 
     def test_dataframe_dtypes(self):
         result = parse_response(EV_RESPONSE, EVOpportunity)
         df = result.to_dataframe()
-        assert df["ev_percent"].dtype == "float64"
+        assert df["ev_percentage"].dtype == "float64"
         assert "str" in str(df["sportsbook"].dtype).lower() or df["sportsbook"].dtype == "object"