vikuna 0.1.0__tar.gz

vikuna-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: vikuna
+Version: 0.1.0
+Summary: Alpaca paper trading environment
+Author-email: William Kruta <wjkruta@gmail.com>
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: alpaca-py>=0.43.2
+Requires-Dist: duckdb>=1.5.1
+Requires-Dist: polars>=1.39.3
+Requires-Dist: pytz>=2024.1
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: yahoors>=0.1.2
+Requires-Dist: build>=1.4.2
+Requires-Dist: twine>=6.2.0
+
+# Vikuna
+
+Lightweight Python library for Alpaca paper trading, portfolio inspection, equity and options market data access, and DuckDB-backed bar caching. The package is structured so trading, account, market data, options, and storage can be used independently.
+
+## Features
+
+- Place and manage Alpaca paper-trading orders
+- Submit advanced equity orders including trailing stop, bracket, OCO, and OTO
+- Read account snapshots and open positions
+- Fetch historical bars and latest quotes
+- Discover option contracts, read option quotes/bars, and place single-leg option orders
+- Submit multi-leg option orders and inspect option chain snapshots with greeks
+- Validate invalid order combinations before hitting the Alpaca API
+- Cache bars locally in DuckDB for incremental sync workflows
+- Work with typed dataclasses and Polars dataframes
+
+## Installation
+
+Use the checked-in `uv` environment when possible:
+
+```bash
+uv sync --dev
+```
+
+Fallback:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -r requirements.txt
+```
+
+## Configuration
+
+Create a local `.env` file from `.env.example`:
+
+```env
+ALPACA_API_KEY=your_api_key_here
+ALPACA_SECRET_KEY=your_secret_key_here
+ALPACA_BASE_URL=https://paper-api.alpaca.markets
+DB_PATH=./data/market_data.duckdb
+```
+
+Use paper-trading credentials for development.
+
+## Quick Start
+
+```python
+from datetime import datetime, timedelta, timezone
+from vikuna import (
+    AlpacaAccountClient,
+    AlpacaMarketData,
+    AlpacaOptionsClient,
+    MarketDatabase,
+    MultiLegOrderRequest,
+    OptionOrderLeg,
+)
+
+account_client = AlpacaAccountClient()
+account = account_client.get_account()
+print(account.portfolio_value)
+
+market_data = AlpacaMarketData()
+db = MarketDatabase()
+
+end = datetime.now(timezone.utc)
+start = end - timedelta(days=30)
+bars = market_data.get_bars("AAPL", "1d", start, end)
+db.save_bars(bars)
+
+latest = db.get_latest_timestamp("AAPL", "1d")
+print(latest)
+db.close()
+
+options = AlpacaOptionsClient()
+contracts = options.list_contracts("AAPL", contract_type="call", limit=5)
+print(contracts)
+
+chain = options.get_chain_snapshot("AAPL", contract_type="call")
+print(chain.select(["symbol", "bid_price", "ask_price", "delta", "theta"]))
+
+db.save_option_bars(options.get_bars("AAPL240621C00190000", "1d", start, end))
+db.save_option_snapshots(options.list_chain_snapshots("AAPL", contract_type="call"))
+
+spread = MultiLegOrderRequest(
+    qty=1,
+    order_type="limit",
+    limit_price=1.25,
+    legs=[
+        OptionOrderLeg("AAPL240621C00190000", "buy", "buy_to_open"),
+        OptionOrderLeg("AAPL240621C00200000", "sell", "sell_to_open"),
+    ],
+)
+# options.submit_multileg_order(spread)
+```
+
+## API Overview
+
+- `AlpacaTradingClient`: `buy`, `sell`, `cancel_order`, `cancel_all_orders`, `get_order`, `list_orders`
+- `AlpacaAccountClient`: `get_account`, `get_positions`, `get_position`, `close_position`, `close_all_positions`
+- `AlpacaMarketData`: `get_bars`, `get_latest_bar`, `get_quote`
+- `AlpacaOptionsClient`: `list_contracts`, `get_contract`, `get_bars`, `get_latest_quote`, `buy`, `sell`
+- `AlpacaOptionsClient`: also `submit_multileg_order` and `get_chain_snapshot`
+- `AlpacaOptionsClient`: also `list_chain_snapshots` for typed snapshot objects
+- `MarketDatabase`: `save_bars`, `load_bars`, `get_latest_timestamp`, `sync`
+- `MarketDatabase`: also `save_option_bars`, `load_option_bars`, `get_latest_option_timestamp`, `sync_option_bars`
+- `MarketDatabase`: also `save_option_snapshots`, `load_option_snapshots`, `sync_option_snapshots`
+
+Shared types exported by the package:
+
+- `Bar`
+- `Order`
+- `Position`
+- `Account`
+- `OptionContract`
+- `OptionOrderLeg`
+- `MultiLegOrderRequest`
+- `OptionQuote`
+- `OptionSnapshot`
+- `BAR_SCHEMA`
+
+## Notes
+
+- Options support is implemented against Alpaca’s current options trading and market data APIs.
+- Futures are not implemented in this library yet because Alpaca does not expose a stable futures API surface here.
+
+## Development
+
+Run the test suite:
+
+```bash
+.venv/bin/python -m pytest tests -q
+```
+
+Run the local smoke example:
+
+```bash
+python main.py
+```

vikuna-0.1.0/README.md

@@ -0,0 +1,139 @@
+# Vikuna
+
+Lightweight Python library for Alpaca paper trading, portfolio inspection, equity and options market data access, and DuckDB-backed bar caching. The package is structured so trading, account, market data, options, and storage can be used independently.
+
+## Features
+
+- Place and manage Alpaca paper-trading orders
+- Submit advanced equity orders including trailing stop, bracket, OCO, and OTO
+- Read account snapshots and open positions
+- Fetch historical bars and latest quotes
+- Discover option contracts, read option quotes/bars, and place single-leg option orders
+- Submit multi-leg option orders and inspect option chain snapshots with greeks
+- Validate invalid order combinations before hitting the Alpaca API
+- Cache bars locally in DuckDB for incremental sync workflows
+- Work with typed dataclasses and Polars dataframes
+
+## Installation
+
+Use the checked-in `uv` environment when possible:
+
+```bash
+uv sync --dev
+```
+
+Fallback:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -r requirements.txt
+```
+
+## Configuration
+
+Create a local `.env` file from `.env.example`:
+
+```env
+ALPACA_API_KEY=your_api_key_here
+ALPACA_SECRET_KEY=your_secret_key_here
+ALPACA_BASE_URL=https://paper-api.alpaca.markets
+DB_PATH=./data/market_data.duckdb
+```
+
+Use paper-trading credentials for development.
+
+## Quick Start
+
+```python
+from datetime import datetime, timedelta, timezone
+from vikuna import (
+    AlpacaAccountClient,
+    AlpacaMarketData,
+    AlpacaOptionsClient,
+    MarketDatabase,
+    MultiLegOrderRequest,
+    OptionOrderLeg,
+)
+
+account_client = AlpacaAccountClient()
+account = account_client.get_account()
+print(account.portfolio_value)
+
+market_data = AlpacaMarketData()
+db = MarketDatabase()
+
+end = datetime.now(timezone.utc)
+start = end - timedelta(days=30)
+bars = market_data.get_bars("AAPL", "1d", start, end)
+db.save_bars(bars)
+
+latest = db.get_latest_timestamp("AAPL", "1d")
+print(latest)
+db.close()
+
+options = AlpacaOptionsClient()
+contracts = options.list_contracts("AAPL", contract_type="call", limit=5)
+print(contracts)
+
+chain = options.get_chain_snapshot("AAPL", contract_type="call")
+print(chain.select(["symbol", "bid_price", "ask_price", "delta", "theta"]))
+
+db.save_option_bars(options.get_bars("AAPL240621C00190000", "1d", start, end))
+db.save_option_snapshots(options.list_chain_snapshots("AAPL", contract_type="call"))
+
+spread = MultiLegOrderRequest(
+    qty=1,
+    order_type="limit",
+    limit_price=1.25,
+    legs=[
+        OptionOrderLeg("AAPL240621C00190000", "buy", "buy_to_open"),
+        OptionOrderLeg("AAPL240621C00200000", "sell", "sell_to_open"),
+    ],
+)
+# options.submit_multileg_order(spread)
+```
+
+## API Overview
+
+- `AlpacaTradingClient`: `buy`, `sell`, `cancel_order`, `cancel_all_orders`, `get_order`, `list_orders`
+- `AlpacaAccountClient`: `get_account`, `get_positions`, `get_position`, `close_position`, `close_all_positions`
+- `AlpacaMarketData`: `get_bars`, `get_latest_bar`, `get_quote`
+- `AlpacaOptionsClient`: `list_contracts`, `get_contract`, `get_bars`, `get_latest_quote`, `buy`, `sell`
+- `AlpacaOptionsClient`: also `submit_multileg_order` and `get_chain_snapshot`
+- `AlpacaOptionsClient`: also `list_chain_snapshots` for typed snapshot objects
+- `MarketDatabase`: `save_bars`, `load_bars`, `get_latest_timestamp`, `sync`
+- `MarketDatabase`: also `save_option_bars`, `load_option_bars`, `get_latest_option_timestamp`, `sync_option_bars`
+- `MarketDatabase`: also `save_option_snapshots`, `load_option_snapshots`, `sync_option_snapshots`
+
+Shared types exported by the package:
+
+- `Bar`
+- `Order`
+- `Position`
+- `Account`
+- `OptionContract`
+- `OptionOrderLeg`
+- `MultiLegOrderRequest`
+- `OptionQuote`
+- `OptionSnapshot`
+- `BAR_SCHEMA`
+
+## Notes
+
+- Options support is implemented against Alpaca’s current options trading and market data APIs.
+- Futures are not implemented in this library yet because Alpaca does not expose a stable futures API surface here.
+
+## Development
+
+Run the test suite:
+
+```bash
+.venv/bin/python -m pytest tests -q
+```
+
+Run the local smoke example:
+
+```bash
+python main.py
+```

vikuna-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "vikuna"
+version = "0.1.0"
+description = "Alpaca paper trading environment"
+authors = [{ name = "William Kruta", email = "wjkruta@gmail.com" }]
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "alpaca-py>=0.43.2",
+    "duckdb>=1.5.1",
+    "polars>=1.39.3",
+    "pytz>=2024.1",
+    "python-dotenv>=1.2.2",
+    "yahoors>=0.1.2",
+    "build>=1.4.2",
+    "twine>=6.2.0",
+]
+
+[project.scripts]
+alpacatrading = "main:main"
+
+[dependency-groups]
+dev = ["pytest", "pytest-mock"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"

vikuna-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vikuna-0.1.0/tests/test_account.py

@@ -0,0 +1,50 @@
+from datetime import datetime, timezone
+from decimal import Decimal
+from unittest.mock import MagicMock, patch
+
+import polars as pl
+import pytest
+
+from alpaca_trading.account import AlpacaAccountClient
+
+
+def make_utc(*args):
+    return datetime(*args, tzinfo=timezone.utc)
+
+
+def make_position(symbol="AAPL", side="long", asset_class="us_equity"):
+    position = MagicMock()
+    position.symbol = symbol
+    position.qty = Decimal("10")
+    position.side = MagicMock(value=side)
+    position.avg_entry_price = Decimal("185.50")
+    position.current_price = Decimal("188.00")
+    position.market_value = Decimal("1880.00")
+    position.unrealized_pl = Decimal("25.00")
+    position.unrealized_plpc = Decimal("0.0135")
+    position.asset_class = MagicMock(value=asset_class)
+    return position
+
+
+@pytest.fixture
+def mock_trading_client():
+    with patch("alpaca_trading.account.TradingClient") as mock_client:
+        yield mock_client.return_value
+
+
+@pytest.fixture
+def client(mock_trading_client):
+    return AlpacaAccountClient(api_key="test_key", secret_key="test_secret")
+
+
+def test_get_positions_can_filter_option_positions(client, mock_trading_client):
+    mock_trading_client.get_all_positions.return_value = [
+        make_position("AAPL", asset_class="us_equity"),
+        make_position("AAPL240621C00190000", asset_class="us_option"),
+    ]
+
+    result = client.get_option_positions()
+
+    assert isinstance(result, pl.DataFrame)
+    assert len(result) == 1
+    assert result["ticker"][0] == "AAPL240621C00190000"

vikuna-0.1.0/tests/test_db.py

@@ -0,0 +1,142 @@
+from datetime import datetime, timedelta, timezone
+from unittest.mock import MagicMock
+
+import polars as pl
+import pytest
+
+from alpaca_trading.data_types import BAR_SCHEMA, OptionSnapshot
+from alpaca_trading.db import MarketDatabase
+
+
+def make_utc(*args):
+    return datetime(*args, tzinfo=timezone.utc)
+
+
+def sample_bars_df(ticker="AAPL", interval="1d", n=3):
+    base = make_utc(2024, 1, 2)
+    return pl.DataFrame(
+        {
+            "ticker": [ticker] * n,
+            "interval": [interval] * n,
+            "timestamp": [base + timedelta(days=i) for i in range(n)],
+            "open": [185.0 + i for i in range(n)],
+            "high": [186.0 + i for i in range(n)],
+            "low": [184.0 + i for i in range(n)],
+            "close": [185.5 + i for i in range(n)],
+            "volume": [50_000_000 + i * 1000 for i in range(n)],
+            "vwap": [185.2 + i for i in range(n)],
+            "trade_count": [300_000 + i * 100 for i in range(n)],
+        },
+        schema=BAR_SCHEMA,
+    )
+
+
+def sample_option_snapshots():
+    return [
+        OptionSnapshot(
+            symbol="AAPL240621C00190000",
+            bid_price=4.5,
+            ask_price=4.6,
+            bid_size=10,
+            ask_size=12,
+            implied_volatility=0.28,
+            delta=0.52,
+            gamma=0.08,
+            rho=0.03,
+            theta=-0.04,
+            vega=0.11,
+        ),
+        OptionSnapshot(
+            symbol="AAPL240621P00190000",
+            bid_price=3.8,
+            ask_price=3.9,
+            bid_size=8,
+            ask_size=9,
+            implied_volatility=0.31,
+            delta=-0.48,
+            gamma=0.07,
+            rho=-0.02,
+            theta=-0.03,
+            vega=0.10,
+        ),
+    ]
+
+
+@pytest.fixture
+def db():
+    database = MarketDatabase(db_path=":memory:")
+    yield database
+    database.close()
+
+
+def test_save_and_load_bars(db):
+    df = sample_bars_df()
+    db.save_bars(df)
+    result = db.load_bars("AAPL", "1d", make_utc(2024, 1, 1), make_utc(2024, 1, 10))
+    assert len(result) == 3
+    assert result["ticker"][0] == "AAPL"
+
+
+def test_get_latest_timestamp_returns_max(db):
+    db.save_bars(sample_bars_df(n=3))
+    ts = db.get_latest_timestamp("AAPL", "1d")
+    assert ts == datetime(2024, 1, 4, tzinfo=timezone.utc)
+
+
+def test_sync_fetches_and_saves_new_bars(db):
+    mock_market_data = MagicMock()
+    new_bars = sample_bars_df(n=5)
+    mock_market_data.get_bars.return_value = new_bars
+
+    result = db.sync("AAPL", "1d", mock_market_data)
+
+    assert len(result) == 5
+    stored = db.load_bars("AAPL", "1d", make_utc(2024, 1, 1), make_utc(2024, 1, 10))
+    assert len(stored) == 5
+
+
+def test_save_and_load_option_bars(db):
+    df = sample_bars_df(ticker="AAPL240621C00190000")
+    db.save_option_bars(df)
+    result = db.load_option_bars(
+        "AAPL240621C00190000",
+        "1d",
+        make_utc(2024, 1, 1),
+        make_utc(2024, 1, 10),
+    )
+    assert len(result) == 3
+    assert result["ticker"][0] == "AAPL240621C00190000"
+
+
+def test_sync_option_bars_fetches_and_saves_new_bars(db):
+    mock_options_data = MagicMock()
+    new_bars = sample_bars_df(ticker="AAPL240621C00190000", n=4)
+    mock_options_data.get_bars.return_value = new_bars
+
+    result = db.sync_option_bars("AAPL240621C00190000", "1d", mock_options_data)
+
+    assert len(result) == 4
+    stored = db.load_option_bars(
+        "AAPL240621C00190000",
+        "1d",
+        make_utc(2024, 1, 1),
+        make_utc(2024, 1, 10),
+    )
+    assert len(stored) == 4
+
+
+def test_save_and_load_option_snapshots(db):
+    db.save_option_snapshots(sample_option_snapshots())
+    result = db.load_option_snapshots()
+    assert len(result) == 2
+    assert result["symbol"][0] == "AAPL240621C00190000"
+
+
+def test_sync_option_snapshots_fetches_and_saves_chain(db):
+    mock_options_data = MagicMock()
+    mock_options_data.list_chain_snapshots.return_value = sample_option_snapshots()
+
+    result = db.sync_option_snapshots("AAPL", mock_options_data, contract_type="call")
+
+    assert len(result) == 2
+    mock_options_data.list_chain_snapshots.assert_called_once()

vikuna-0.1.0/tests/test_market_data.py

@@ -0,0 +1,108 @@
+from datetime import datetime, timezone
+from unittest.mock import MagicMock, patch
+
+import polars as pl
+import pytest
+from alpaca.common.exceptions import APIError
+
+from alpaca_trading.data_types import Bar
+from alpaca_trading.market_data import AlpacaMarketData
+
+
+def make_utc(*args):
+    return datetime(*args, tzinfo=timezone.utc)
+
+
+def make_alpaca_bar(ts, o, h, l, c, v, vwap=None, trade_count=None):
+    bar = MagicMock()
+    bar.timestamp = ts
+    bar.open = o
+    bar.high = h
+    bar.low = l
+    bar.close = c
+    bar.volume = v
+    bar.vwap = vwap
+    bar.trade_count = trade_count
+    return bar
+
+
+@pytest.fixture
+def mock_data_client():
+    with patch("alpaca_trading.market_data.StockHistoricalDataClient") as mock_client:
+        yield mock_client.return_value
+
+
+@pytest.fixture
+def mock_yahoo():
+    with patch("alpaca_trading.market_data.Candles") as mock_yahoo_cls:
+        yield mock_yahoo_cls.return_value
+
+
+@pytest.fixture
+def market_data(mock_data_client, mock_yahoo):
+    return AlpacaMarketData(api_key="test_key", secret_key="test_secret")
+
+
+def test_get_bars_returns_polars_dataframe(market_data, mock_data_client):
+    alpaca_bar = make_alpaca_bar(make_utc(2024, 1, 2), 185.0, 186.5, 184.0, 185.9, 50_000_000, 185.4, 312_000)
+    bar_set = MagicMock()
+    bar_set.__getitem__ = MagicMock(return_value=[alpaca_bar])
+    mock_data_client.get_stock_bars.return_value = bar_set
+
+    result = market_data.get_bars("AAPL", "1d", make_utc(2024, 1, 1), make_utc(2024, 1, 3))
+
+    assert isinstance(result, pl.DataFrame)
+    assert len(result) == 1
+    assert result["ticker"][0] == "AAPL"
+
+
+def test_get_bars_falls_back_to_yahoo_on_api_error(market_data, mock_data_client, mock_yahoo):
+    mock_data_client.get_stock_bars.side_effect = APIError({"message": "subscription does not permit querying recent SIP data"})
+    mock_yahoo.get_candles.return_value = pl.DataFrame(
+        {
+            "date": [make_utc(2024, 1, 2)],
+            "ticker": ["AAPL"],
+            "interval": ["1d"],
+            "close": [185.9],
+            "open": [185.0],
+            "low": [184.0],
+            "high": [186.5],
+            "volume": [50_000_000],
+        }
+    )
+
+    result = market_data.get_bars("AAPL", "1d", make_utc(2024, 1, 1), make_utc(2024, 1, 3))
+
+    assert len(result) == 1
+    assert result["close"][0] == 185.9
+
+
+def test_get_latest_bar_falls_back_to_yahoo(market_data, mock_data_client, mock_yahoo):
+    mock_data_client.get_stock_latest_bar.side_effect = APIError({"message": "subscription does not permit querying recent SIP data"})
+    mock_yahoo.get_candles.return_value = pl.DataFrame(
+        {
+            "date": [make_utc(2024, 1, 2)],
+            "ticker": ["AAPL"],
+            "interval": ["1d"],
+            "close": [185.9],
+            "open": [185.0],
+            "low": [184.0],
+            "high": [186.5],
+            "volume": [50_000_000],
+        }
+    )
+
+    result = market_data.get_latest_bar("AAPL", "1d")
+
+    assert isinstance(result, Bar)
+    assert result.close == 185.9
+
+
+def test_get_quote_falls_back_to_yahoo_last_price(market_data, mock_data_client, mock_yahoo):
+    mock_data_client.get_stock_latest_quote.side_effect = APIError({"message": "subscription does not permit querying recent SIP data"})
+    mock_yahoo.get_last_price.return_value = {"AAPL": 185.9}
+
+    result = market_data.get_quote("AAPL")
+
+    assert result["bid"] == 185.9
+    assert result["ask"] == 185.9