optionsahoy-langchain 0.1.1

LangChain tools for the OptionsAhoy equity-compensation calculators.

optionsahoy-langchain

LangChain tools for the OptionsAhoy equity-compensation calculators. One StructuredTool per OptionsAhoy REST endpoint, built on the keyless optionsahoy client. No OptionsAhoy account, no application programming interface (API) key, full federal tax code plus all 50 states and the District of Columbia (DC).

Why not just ask the model?

We benchmarked five frontier large language models (LLMs), 3 runs each, 15 trials total, on the same multi-year incentive stock option (ISO) exercise problem. Every trial overshot the true after-tax outcome, by 2x to 20x. Multi-year scheduling has a search space larger than an LLM can reason through in-context; these tools return the verifiable answer instead.

Raw responses and scoring: llm-iso-benchmark. Full write-up: But can it do taxes though?.

What it provides

get_optionsahoy_tools() returns seven StructuredTools, each with a pydantic args_schema mirroring its endpoint:

• optionsahoy_amt_iso_optimize - multi-year ISO exercise optimizer under the alternative minimum tax (AMT)
• optionsahoy_nso_calculate - non-qualified stock option (NSO) exercise tax, sell-at-exercise versus hold
• optionsahoy_rsu_sell_vs_hold - restricted stock unit (RSU) sell at vest versus hold for long-term capital gains
• optionsahoy_concentration_analyze - single-stock concentration risk and the after-tax cost of diversifying
• optionsahoy_protective_put_price - protective put and zero-cost collar pricing
• optionsahoy_qsbs_check - qualified small business stock (QSBS) Section 1202 eligibility and exclusion
• optionsahoy_equity_funding_plan - multi-year plan to fund a cash goal from equity by a target date

Coverage spans the full federal tax code plus all 50 states and DC. The adapter pulls in the keyless optionsahoy client automatically. No API key is read, stored, or sent anywhere.

Install

pip install optionsahoy-langchain

Quickstart

Bind the tools to any tool-calling chat model and run a minimal tool-calling loop:

import os

from langchain_core.messages import AIMessage, HumanMessage, SystemMessage, ToolMessage
from langchain_openai import ChatOpenAI  # pip install langchain-openai; set OPENAI_API_KEY

from langchain_optionsahoy import get_optionsahoy_tools

tools = get_optionsahoy_tools()
tools_by_name = {t.name: t for t in tools}

model = ChatOpenAI(model="gpt-4o-mini", temperature=0)
model_with_tools = model.bind_tools(tools)

messages = [
    SystemMessage(content=(
        "You are an equity-compensation assistant. Use the OptionsAhoy tools to "
        "compute exact tax-aware answers; do not estimate the math yourself."
    )),
    HumanMessage(content=(
        "I have 8000 ISOs at a $3 strike, current fair market value $40, granted "
        "2022-03-01, still employed. I file single in California with $250000 of "
        "ordinary income, no AMT carryforward, 4% cash return, 5-year horizon. "
        "How many shares should I exercise each year? "
        "Use the optionsahoy_amt_iso_optimize tool."
    )),
]

# Minimal tool-calling loop: invoke the model, run any tools it requests,
# append results as ToolMessages, repeat until it gives a final answer.
for _ in range(5):
    ai: AIMessage = model_with_tools.invoke(messages)
    messages.append(ai)
    if not ai.tool_calls:
        print(ai.content)
        break
    for call in ai.tool_calls:
        result = tools_by_name[call["name"]].invoke(call["args"])
        messages.append(ToolMessage(content=str(result), tool_call_id=call["id"]))

Pass your own configured client with get_optionsahoy_tools(client=OptionsAhoyClient(...)).

The seven endpoints accept forward-looking fields (such as expectedSalePrice or volatility) that the schema marks optional but the API requires at call time; set a covered ticker (for example "NVDA") to let the API derive them, or pass explicit values. Omitting both returns a clear 400 explaining which field is needed.

Runnable example and source

• Runnable example: examples/
• Source: integrations/python/optionsahoy-langchain

Related

Sibling packages wrapping the same calculators:

• optionsahoy - plain Python client (no framework)
• llama-index-tools-optionsahoy - LlamaIndex tools
• crewai-optionsahoy - CrewAI tools

Other surfaces for the same calculators:

• Hosted Model Context Protocol (MCP) server: https://optionsahoy.com/mcp
• Agent integration docs: https://optionsahoy.com/for-agents
• Free in-browser calculators: https://optionsahoy.com/tools

Built by AlphaLatitude Inc., the company behind OptionsAhoy.