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
```
