optionda 0.1.0__tar.gz

optionda-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuanben
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

optionda-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: optionda
+Version: 0.1.0
+Summary: Terminal options desk: freeze IV, reprice on live spot (Yahoo or Alpaca).
+Author: Yuanben
+License: MIT
+Project-URL: Homepage, https://github.com/ybenzou/optionda
+Keywords: options,black-scholes,cli,alpaca,yfinance
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Requires-Dist: yfinance>=0.2.40
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# optionda
+
+Terminal options desk: manage small multi-account option books, freeze IV, and reprice on live underlying prints.
+
+```bash
+pip install optionda
+# or from this repo:
+pip install -e ./optionda
+```
+
+**MODEL marks only** — delayed/indicative data, not executable quotes.
+
+## Quick start (no API key)
+
+Requires Python 3.11+.
+
+```bash
+py -3.11 -m venv .venv
+source .venv/Scripts/activate
+pip install -e .
+
+# one-time (like conda init)
+optionda init
+eval "$(optionda shellenv)"   # or open a new shell — default prompt: [optionda] (cyan)
+
+optionda create demo
+optionda activate demo        # prompt → [demo]
+optionda deactivate           # prompt → [optionda]
+optionda activate hedge       # prompt → [hedge]
+
+optionda add AAPL270115C00200000 --qty 2 --entry 5.20
+
+# per-line qty + cost (semicolon batch):
+optionda add "INTC 261016 140 C x10 @ 3.482; SKHY 261016 200 C x1 @ 9.5"
+
+# easiest batch: bare add → paste lines → blank line to finish
+optionda add
+# INTC 261016 140 C x10 @ 3.482
+# TSLA 261218 500 C x2 @ 5.75
+# <empty line>
+
+optionda export
+optionda run
+```
+
+`pip install` cannot safely edit your shell config (unlike the Conda installer). Run **`optionda init` once**, then **`optionda activate <name>`** each session (like `conda activate`). Undo init with `optionda init --reverse`.
+
+Without `activate`, `export` / `run` / `add` / `delete` cannot read or change any account book — only the session-active account is visible.
+
+**Cost is required on every `add`**: use `@ 5.20` on the line or `--entry 5.20`. Re-adding the same OCC+side merges qty and sets cost to the quantity-weighted average `(q1·c1 + q2·c2) / (q1+q2)`.
+
+`add` **without** `--iv` pulls IV from Alpaca (if key configured) or Yahoo. Use `--iv` only as fallback.
+
+In the table, **`Model$`** is the Black–Scholes theoretical premium (per share), **`Cost`** is your avg entry, and **`uPnL$`** compares them. Not a live option bid/ask.
+
+UI uses **Rich** (`Panel`, `Rule`, `Table`, `Live` spinner). No `tqdm` / `popen` required for the desk view.
+
+## Optional Alpaca key (15s refresh)
+
+```bash
+optionda key alpaca <KEY_ID> <SECRET>   # verifies against Alpaca before saving
+optionda key status                     # re-checks live credentials
+optionda run                            # refresh every 15s
+optionda key clear alpaca
+```
+
+`key alpaca` probes `data.alpaca.markets` (SPY latest trade). Invalid keys are **not** saved.
+
+Credentials live in `~/.optionda/credentials.toml` (mode `0600` when the OS allows). Override the data root with `OPTIONDA_HOME`.
+
+Per-account tracking files (under the optionda data library, **not** your shell cwd):
+
+Two separate write paths:
+
+| Path | Role | Write mode |
+|------|------|------------|
+| `~/.optionda/books/<account>.txt` | Current book only (human snapshot) | **Overwrite** on add/delete/refresh |
+| `~/.optionda/logs/<account>.jsonl` | Full event stream for charts / history | **Append only** |
+| `~/.optionda/surfaces/<underlying>.json` | Last valid Alpaca IV smile | **Overwrite** only on successful `refresh-iv` |
+
+JSONL `event` types: `add`, `merge`, `delete`, `refresh_iv`, `export`, `run`.  
+`refresh_iv` records calibrated surface metadata. `export`/`run` rows include `valuation_mode`, `surface_iv`, and `surface_as_of`.
+
+```bash
+optionda add …          # rewrite book + append add/merge event
+optionda delete …       # rewrite book + append delete event
+optionda refresh-iv     # calibrate Alpaca vendor-IV smiles while quotes are fresh
+optionda export         # print surface/frozen Model$ + append export mark
+optionda run            # each tick appends a run mark
+```
+
+**Spot (24/5):** Alpaca stock spots query `overnight` → `boats` → `delayed_sip` → `iex` and keep the **newest** trade/quote. Basic plans usually get `overnight` (≈Futu night session); `boats` needs a higher data tier.
+
+### Local overnight IV surface
+
+Run `optionda refresh-iv` **during the US option session**, when Alpaca chain quotes are current. It collects valid Alpaca vendor-IV nodes, filters zero/wide/stale quotes, and saves a per-underlying expiry smile.
+
+At night, `run` / `export` update the 24/5 stock Spot, use the saved expiry smile with **sticky delta** interpolation, and then reprice with Black–Scholes. The `IVsrc` column is `surface` when this succeeds and `frozen` when optionda falls back to the stored position IV. Surfaces older than 36 hours are not used.
+
+This is a local, auditable model—not a copy of Futu's proprietary IV surface. Alpaca's free `indicative` chain is still the calibration input; OPRA improves the input only when the user has a subscription. optionda deliberately does **not** infer a new IV from frozen overnight option quotes.
+
+```toml
+# ~/.optionda/config.toml
+alpaca_options_feed = "auto"       # try opra, then indicative
+```
+
+For a paid match to exchange IV, subscribe to Alpaca OPRA.
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `optionda create <name>` | Create account |
+| `optionda list` | List accounts (`*` = session-active) |
+| `optionda book` | Show current positions (no fetch / no log write) |
+| `optionda activate <name>` | Session-activate (prompt → cyan `[name]`) |
+| `optionda deactivate` | Back to cyan `[optionda]` |
+| `optionda init` | Persist hook in shell rc (like `conda init`) |
+| `optionda add …` | Add with required cost; same OCC+side merges qty + avg cost |
+| `optionda delete <id\|OCC>` | Remove position |
+| `optionda refresh-iv` | Calibrate local Alpaca IV smiles and refresh fallback IVs |
+| `optionda run` | Live table until Ctrl+C |
+| `optionda export` | One-shot snapshot |
+| `optionda key …` | Configure Alpaca credentials |
+
+## Repository
+
+Standalone project: [github.com/ybenzou/optionda](https://github.com/ybenzou/optionda). Not part of the Next.js frontend app.

optionda-0.1.0/README.md

@@ -0,0 +1,128 @@
+# optionda
+
+Terminal options desk: manage small multi-account option books, freeze IV, and reprice on live underlying prints.
+
+```bash
+pip install optionda
+# or from this repo:
+pip install -e ./optionda
+```
+
+**MODEL marks only** — delayed/indicative data, not executable quotes.
+
+## Quick start (no API key)
+
+Requires Python 3.11+.
+
+```bash
+py -3.11 -m venv .venv
+source .venv/Scripts/activate
+pip install -e .
+
+# one-time (like conda init)
+optionda init
+eval "$(optionda shellenv)"   # or open a new shell — default prompt: [optionda] (cyan)
+
+optionda create demo
+optionda activate demo        # prompt → [demo]
+optionda deactivate           # prompt → [optionda]
+optionda activate hedge       # prompt → [hedge]
+
+optionda add AAPL270115C00200000 --qty 2 --entry 5.20
+
+# per-line qty + cost (semicolon batch):
+optionda add "INTC 261016 140 C x10 @ 3.482; SKHY 261016 200 C x1 @ 9.5"
+
+# easiest batch: bare add → paste lines → blank line to finish
+optionda add
+# INTC 261016 140 C x10 @ 3.482
+# TSLA 261218 500 C x2 @ 5.75
+# <empty line>
+
+optionda export
+optionda run
+```
+
+`pip install` cannot safely edit your shell config (unlike the Conda installer). Run **`optionda init` once**, then **`optionda activate <name>`** each session (like `conda activate`). Undo init with `optionda init --reverse`.
+
+Without `activate`, `export` / `run` / `add` / `delete` cannot read or change any account book — only the session-active account is visible.
+
+**Cost is required on every `add`**: use `@ 5.20` on the line or `--entry 5.20`. Re-adding the same OCC+side merges qty and sets cost to the quantity-weighted average `(q1·c1 + q2·c2) / (q1+q2)`.
+
+`add` **without** `--iv` pulls IV from Alpaca (if key configured) or Yahoo. Use `--iv` only as fallback.
+
+In the table, **`Model$`** is the Black–Scholes theoretical premium (per share), **`Cost`** is your avg entry, and **`uPnL$`** compares them. Not a live option bid/ask.
+
+UI uses **Rich** (`Panel`, `Rule`, `Table`, `Live` spinner). No `tqdm` / `popen` required for the desk view.
+
+## Optional Alpaca key (15s refresh)
+
+```bash
+optionda key alpaca <KEY_ID> <SECRET>   # verifies against Alpaca before saving
+optionda key status                     # re-checks live credentials
+optionda run                            # refresh every 15s
+optionda key clear alpaca
+```
+
+`key alpaca` probes `data.alpaca.markets` (SPY latest trade). Invalid keys are **not** saved.
+
+Credentials live in `~/.optionda/credentials.toml` (mode `0600` when the OS allows). Override the data root with `OPTIONDA_HOME`.
+
+Per-account tracking files (under the optionda data library, **not** your shell cwd):
+
+Two separate write paths:
+
+| Path | Role | Write mode |
+|------|------|------------|
+| `~/.optionda/books/<account>.txt` | Current book only (human snapshot) | **Overwrite** on add/delete/refresh |
+| `~/.optionda/logs/<account>.jsonl` | Full event stream for charts / history | **Append only** |
+| `~/.optionda/surfaces/<underlying>.json` | Last valid Alpaca IV smile | **Overwrite** only on successful `refresh-iv` |
+
+JSONL `event` types: `add`, `merge`, `delete`, `refresh_iv`, `export`, `run`.  
+`refresh_iv` records calibrated surface metadata. `export`/`run` rows include `valuation_mode`, `surface_iv`, and `surface_as_of`.
+
+```bash
+optionda add …          # rewrite book + append add/merge event
+optionda delete …       # rewrite book + append delete event
+optionda refresh-iv     # calibrate Alpaca vendor-IV smiles while quotes are fresh
+optionda export         # print surface/frozen Model$ + append export mark
+optionda run            # each tick appends a run mark
+```
+
+**Spot (24/5):** Alpaca stock spots query `overnight` → `boats` → `delayed_sip` → `iex` and keep the **newest** trade/quote. Basic plans usually get `overnight` (≈Futu night session); `boats` needs a higher data tier.
+
+### Local overnight IV surface
+
+Run `optionda refresh-iv` **during the US option session**, when Alpaca chain quotes are current. It collects valid Alpaca vendor-IV nodes, filters zero/wide/stale quotes, and saves a per-underlying expiry smile.
+
+At night, `run` / `export` update the 24/5 stock Spot, use the saved expiry smile with **sticky delta** interpolation, and then reprice with Black–Scholes. The `IVsrc` column is `surface` when this succeeds and `frozen` when optionda falls back to the stored position IV. Surfaces older than 36 hours are not used.
+
+This is a local, auditable model—not a copy of Futu's proprietary IV surface. Alpaca's free `indicative` chain is still the calibration input; OPRA improves the input only when the user has a subscription. optionda deliberately does **not** infer a new IV from frozen overnight option quotes.
+
+```toml
+# ~/.optionda/config.toml
+alpaca_options_feed = "auto"       # try opra, then indicative
+```
+
+For a paid match to exchange IV, subscribe to Alpaca OPRA.
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `optionda create <name>` | Create account |
+| `optionda list` | List accounts (`*` = session-active) |
+| `optionda book` | Show current positions (no fetch / no log write) |
+| `optionda activate <name>` | Session-activate (prompt → cyan `[name]`) |
+| `optionda deactivate` | Back to cyan `[optionda]` |
+| `optionda init` | Persist hook in shell rc (like `conda init`) |
+| `optionda add …` | Add with required cost; same OCC+side merges qty + avg cost |
+| `optionda delete <id\|OCC>` | Remove position |
+| `optionda refresh-iv` | Calibrate local Alpaca IV smiles and refresh fallback IVs |
+| `optionda run` | Live table until Ctrl+C |
+| `optionda export` | One-shot snapshot |
+| `optionda key …` | Configure Alpaca credentials |
+
+## Repository
+
+Standalone project: [github.com/ybenzou/optionda](https://github.com/ybenzou/optionda). Not part of the Next.js frontend app.

optionda-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "optionda"
+version = "0.1.0"
+description = "Terminal options desk: freeze IV, reprice on live spot (Yahoo or Alpaca)."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [{ name = "Yuanben" }]
+keywords = ["options", "black-scholes", "cli", "alpaca", "yfinance"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Financial and Insurance Industry",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Office/Business :: Financial :: Investment",
+]
+dependencies = [
+  "httpx>=0.27",
+  "pydantic>=2.7",
+  "rich>=13.7",
+  "typer>=0.12",
+  "yfinance>=0.2.40",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.scripts]
+optionda = "optionda.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/ybenzou/optionda"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

optionda-0.1.0/setup.cfg

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

optionda-0.1.0/src/optionda/__init__.py

@@ -0,0 +1,3 @@
+"""optionda — terminal options desk (MODEL marks, frozen IV)."""
+
+__version__ = "0.1.0"

optionda-0.1.0/src/optionda/add_resolve.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from optionda.batch import read_batch_lines
+from optionda.occ import OccError, parse_leg_line
+
+
+def split_semi_separated(text: str) -> list[str]:
+    """Split 'A; B; C' into position lines (keeps spaces inside each part)."""
+    parts = [p.strip() for p in text.replace("\n", ";").split(";")]
+    return [p for p in parts if p and not p.startswith("#")]
+
+
+def read_interactive_lines(
+    *,
+    prompt_print=print,
+    line_input=input,
+) -> list[str]:
+    """Read pasted lines until a blank line or EOF (Ctrl+Z Enter on Windows)."""
+    prompt_print("Paste positions (one per line): ROOT YYMMDD STRIKE C|P xQTY @ cost")
+    prompt_print("Finish with an empty line, or Ctrl+Z then Enter (Windows).")
+    prompt_print("")
+    lines: list[str] = []
+    while True:
+        try:
+            line = line_input()
+        except EOFError:
+            break
+        if not line.strip():
+            break
+        if line.strip().startswith("#"):
+            continue
+        lines.append(line.strip())
+    return lines
+
+
+def _validated_line(token: str) -> str:
+    """Validate parseability but keep the original text (preserves @ cost)."""
+    parse_leg_line(token)
+    return token.strip()
+
+
+def resolve_add_lines(items: list[str]) -> list[str]:
+    """Normalize CLI tokens into one or more position lines.
+
+    Supports:
+      - single/multiple OCC symbols (with optional @ cost)
+      - one human line split across argv: INTC 261016 140 C @ 5.20
+      - semicolon-separated in one argv
+      - file path or '-' (stdin) for multi-line batch
+
+    Original line text is preserved so trailing '@ cost' survives.
+    """
+    if not items:
+        raise ValueError("no positions provided")
+
+    if len(items) == 1:
+        token = items[0]
+        if token == "-" or Path(token).is_file():
+            lines = read_batch_lines(token)
+            if not lines:
+                raise ValueError("no positions to add (empty input)")
+            return lines
+        if ";" in token:
+            parts = split_semi_separated(token)
+            if not parts:
+                raise ValueError("no positions to add")
+            return parts
+        try:
+            return [_validated_line(token)]
+        except OccError as exc:
+            raise ValueError(str(exc)) from exc
+
+    # Multiple argv tokens: either many OCCs, or one spaced human line
+    joined = " ".join(items)
+    if ";" in joined:
+        parts = split_semi_separated(joined)
+        if parts:
+            return parts
+
+    try:
+        return [_validated_line(joined)]
+    except OccError:
+        pass
+
+    lines: list[str] = []
+    for token in items:
+        try:
+            lines.append(_validated_line(token))
+        except OccError as exc:
+            raise ValueError(
+                f"could not parse {token!r} (also not a single human line: {joined!r})"
+            ) from exc
+    return lines
+
+
+def looks_like_field_add(
+    items: list[str],
+    underlying: str | None,
+    expiry: str | None,
+    strike: float | None,
+    option_type: str | None,
+) -> bool:
+    return (
+        not items
+        and underlying is not None
+        and expiry is not None
+        and strike is not None
+        and option_type is not None
+    )