crewai-optionsahoy 0.1.2

CrewAI tools for the OptionsAhoy equity-compensation calculators.

crewai-optionsahoy

CrewAI tools for the OptionsAhoy equity-compensation calculators. One crewai.tools.BaseTool 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 CrewAI BaseTools, 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.

Tools: inputs and outputs

Each tool's args_schema lists the required parameters below; every tool also accepts optional forward-looking fields (such as expectedSalePrice, volatility, expectedMarketReturn) and, where noted, a convenience ticker so the API can derive forward-looking inputs from that symbol. Returns are the top-level fields of the response, wrapped as {"ok": true, "result": {...}}; the fields below are those of result.

optionsahoy_amt_iso_optimize

Multi-year incentive stock option (ISO) exercise optimizer under the alternative minimum tax (AMT). Inputs (required): shares: int, strike: float, fmv: float, filingStatus: str, ordinaryIncome: float, stateCode: str, carryforwardCredit: float, horizon: int, cashReturnRate: float, grantDate: str, hasLeftCompany: bool, terminationDate: str | None. Optional: expectedGrowth, volatility, volatilityDrag, ticker. Returns: crossoverShares, crossoverBargain, alreadyInAmt, stateHasAmt, bargainPerShare, timing, effectiveHorizon, and schedules (lumpSum, evenSplit, optimized), each carrying per-year years[] (shares, bargain, regularFederal, regularState, tmtFederal, tmtState, amtOwedFederal, amtOwedState, creditRecovered, cashTax) plus totalTax, creditEarned, creditRemaining, grossGain, federalLTCG, stateLTCG, nfv.

optionsahoy_nso_calculate

Tax and after-tax proceeds of exercising non-qualified stock options (NSOs), sell-at-exercise versus hold. Inputs (required): shares: int, strike: float, currentPrice: float, ordinaryIncome: float, filingStatus: str, stateCode: str, stillEmployed: bool, holdYears: float, holdFunding: str (sell-to-cover or cash). Optional: expectedSalePrice, haircut, volatility, expectedMarketReturn, ticker. Returns: exercise (bargainElement, federal, state, socialSecurity, medicare, additionalMedicare, total, netCashSellAll), bracketJump (fromRate, toRate, thresholdAtJump), hold (sharesRetained, expectedGain, ltcgTotal, afterTaxProceedsAtSale, netAtYearN), sellNowInvest (netCashAtY0, marketGain, netAtYearN), holdMinusCashless.

optionsahoy_rsu_sell_vs_hold

Sell vested restricted stock units (RSUs) at vest versus hold, on an after-tax, risk-adjusted basis. Inputs (required): shares: int, currentPrice: float, ordinaryIncome: float, filingStatus: str, stateCode: str, stillEmployed: bool, holdYears: float. Optional: expectedSalePrice, haircut, volatility, expectedMarketReturn, ticker. Returns: vest (vestValue, federal, state, medicare, total, netCashAtVest, federalWithheldAtVest), bracketJump, hold (sharesRetained, expectedGain, capGainTotal, isLongTerm, netAtYearN), sellNowInvest (netCashAtY0, marketGain, netAtYearN), holdMinusSell.

optionsahoy_concentration_analyze

Concentrated single-stock position and the after-tax cost of diversifying. Inputs (required): positionValue: float, costBasis: float, acquisitionDate: str, sector: str, stateCode: str, filingStatus: str, ordinaryIncome: float, totalAssets: float. Optional: expectedPositionReturn, expectedMarketReturn, volatility, volatilityDrag, hedgeChoice, ticker. Returns: concentration, riskBand, isLongTermToday, longTermDate, daysUntilLongTerm, lossExposure[] (drop, dollarLoss, newConcentration), waitForLtInsight, schedule[] (planKey, planLabel, yearlySales, totalTax, endOfHorizonWealth, savingsVsLumpSum, wealthByYear), hedging, sectorContextLine, advisorBenchmarkLine.

optionsahoy_protective_put_price

Price a protective put and a zero-cost collar for a stock position. Inputs (required): positionValue: float, sector: str, protectionLevel: float (0.05 to 0.5), tenorYears: float. Optional: volatility, expectedReturn, tickerLabel. Returns: inputs, riskFreeRate, realWorldDrift, barePut (strike, premium, annualCost, annualCostPct, maxLoss, coveredLossAtBadYear), collar (putStrike, callStrike, netPremium, maxLoss, upsideCap, upsideCapPct, isZeroCost), payoffTable[] (drawdownPct, barePutPnl, collarPnl, unhedgedPnl), payoffRange, recommended.

optionsahoy_qsbs_check

Qualified small business stock (QSBS) Section 1202 eligibility and exclusion. Inputs (required): acquisitionDate: str, saleDate: str, entityType: str, acquisitionMethod: str, assetCategory: str, industry: str, activeBusiness: str, adjustedBasis: float, expectedGain: float, stateCode: str, ordinaryIncome: float, filingStatus: str. Returns: verdict, exclusionPercent, perIssuerCap, tenXBasisCap, applicableCap, excludableGain, taxableGain, federalTaxSaved, stateConforms, stateNote, holdingYears, yearsUntilFullExclusion, era, tests[] (id, label, status, detail).

optionsahoy_equity_funding_plan

Plan which equity lots to sell, and when, to fund a cash goal by a target date. Inputs (required): targetAfterTax: float, targetDate: str, ordinaryIncome: float, filingStatus: str, stateCode: str, plus either stacks (preferred; a list of stacks, each with currentPrice and a lots list) or the legacy lots plus currentPrice. Optional: expectedAnnualGrowth, cashInterestRate, riskToleranceShortfall, defaultVolatility, today. Returns: recommended, lockInNow, balanced, holdForGrowth, frontier[], targetAfterTax, targetDateISO, appliedRiskTolerance. Each plan (for example recommended) carries wealthAtTarget, totalTax, shortfallProbability, lockInFraction, and a plan with feasible, totalAfterTaxAchieved, totalSharesSold, totalTaxes, schedule, and remainingPositionValue.

To see the full typed input schema for any tool, call tools[0].args_schema.model_json_schema() (substitute the tool you want). The authoritative request schemas are the OpenAPI spec at https://optionsahoy.com/openapi.json and the agent docs at https://optionsahoy.com/for-agents.

Install

pip install crewai-optionsahoy

Quickstart

Equip a CrewAI agent with the tools and run a crew. CrewAI reads the model from the standard provider environment variables (for example OPENAI_API_KEY):

from crewai import Agent, Crew, Process, Task

from crewai_optionsahoy import get_optionsahoy_tools

tools = get_optionsahoy_tools()

advisor = Agent(
    role="Equity-compensation analyst",
    goal="Answer equity-compensation tax questions using the OptionsAhoy tools.",
    backstory=(
        "You analyze stock-option and equity tax questions for technology workers. "
        "You always call the OptionsAhoy tools for exact numbers instead of "
        "estimating the tax math yourself."
    ),
    tools=tools,
    llm="gpt-4o-mini",
    verbose=True,
)

task = Task(
    description=(
        "A founder acquired original-issuance stock in a US C-corporation on "
        "2018-01-01 for an adjusted basis of $10000, in the tech-software industry, "
        "issuer under $50M in gross assets at issuance and meeting the active-business "
        "test. They plan to sell on 2026-02-01 for an expected gain of $2,000,000. "
        "They file single in California with $250000 of ordinary income. Does this "
        "qualify for QSBS, and how much gain is excludable? "
        "Use the optionsahoy_qsbs_check tool."
    ),
    expected_output="Whether the position qualifies and the dollar amount of excludable gain.",
    agent=advisor,
)

crew = Crew(agents=[advisor], tasks=[task], process=Process.sequential, verbose=True)
print(crew.kickoff())

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/crewai-optionsahoy

Related

Sibling packages wrapping the same calculators:

• optionsahoy - plain Python client (no framework)
• optionsahoy-langchain - LangChain tools
• llama-index-tools-optionsahoy - LlamaIndex 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.