docs: add exotic option API docs, stubs, and changelog entries

Add API documentation for lookback, cliquet, compound, chooser,
Margrabe, forward-start, and quanto option instruments and engines.
Update type stubs and changelog.

Author: quantales

docs/api/instruments.md

@@ -645,8 +645,190 @@ asian_arith = ql.DiscreteAveragingAsianOption(
 asian_arith.setPricingEngine(ql.TurnbullWakemanAsianEngine(process))
 ```
 
+## Lookback Options
+
+### ContinuousFloatingLookbackOption
+
+```{eval-rst}
+.. autoclass:: pyquantlib.ContinuousFloatingLookbackOption
+```
+
+Continuous floating-strike lookback option. The strike is determined at expiry as the minimum (call) or maximum (put) of the asset price over the option's life.
+
+```python
+payoff = ql.FloatingTypePayoff(ql.Call)
+exercise = ql.EuropeanExercise(expiry)
+option = ql.ContinuousFloatingLookbackOption(100.0, payoff, exercise)
+```
+
+### ContinuousFixedLookbackOption
+
+```{eval-rst}
+.. autoclass:: pyquantlib.ContinuousFixedLookbackOption
+```
+
+Continuous fixed-strike lookback option. The payoff is based on the maximum (call) or minimum (put) of the asset price over the option's life.
+
+```python
+payoff = ql.PlainVanillaPayoff(ql.Call, 100.0)
+exercise = ql.EuropeanExercise(expiry)
+option = ql.ContinuousFixedLookbackOption(100.0, payoff, exercise)
+```
+
+### ContinuousPartialFloatingLookbackOption
+
+```{eval-rst}
+.. autoclass:: pyquantlib.ContinuousPartialFloatingLookbackOption
+```
+
+Partial floating-strike lookback option with a lookback period ending before expiry.
+
+```python
+option = ql.ContinuousPartialFloatingLookbackOption(
+    100.0, 1.0, lookback_end, payoff, exercise,
+)
+```
+
+### ContinuousPartialFixedLookbackOption
+
+```{eval-rst}
+.. autoclass:: pyquantlib.ContinuousPartialFixedLookbackOption
+```
+
+Partial fixed-strike lookback option with a lookback period starting after inception.
+
+```python
+option = ql.ContinuousPartialFixedLookbackOption(
+    lookback_start, payoff, exercise,
+)
+```
+
+## Cliquet Options
+
+### CliquetOption
+
+```{eval-rst}
+.. autoclass:: pyquantlib.CliquetOption
+```
+
+Cliquet (ratchet) option with periodic resets. The strike resets at each reset date to the then-current spot price.
+
+```python
+payoff = ql.PercentageStrikePayoff(ql.Call, 1.0)
+exercise = ql.EuropeanExercise(expiry)
+reset_dates = [today + ql.Period(f"{i}M") for i in range(3, 12, 3)]
+option = ql.CliquetOption(payoff, exercise, reset_dates)
+```
+
+## Compound Options
+
+### CompoundOption
+
+```{eval-rst}
+.. autoclass:: pyquantlib.CompoundOption
+```
+
+Compound option (option on an option). The mother option gives the right to buy/sell the daughter option.
+
+```python
+mother_payoff = ql.PlainVanillaPayoff(ql.Call, 5.0)
+mother_exercise = ql.EuropeanExercise(today + ql.Period("6M"))
+daughter_payoff = ql.PlainVanillaPayoff(ql.Call, 100.0)
+daughter_exercise = ql.EuropeanExercise(expiry)
+option = ql.CompoundOption(
+    mother_payoff, mother_exercise, daughter_payoff, daughter_exercise,
+)
+```
+
+## Chooser Options
+
+### SimpleChooserOption
+
+```{eval-rst}
+.. autoclass:: pyquantlib.SimpleChooserOption
+```
+
+Simple chooser option. The holder chooses at a future date whether the option is a call or put.
+
+```python
+option = ql.SimpleChooserOption(choosing_date, 100.0, exercise)
+```
+
+### ComplexChooserOption
+
+```{eval-rst}
+.. autoclass:: pyquantlib.ComplexChooserOption
+```
+
+Complex chooser option with different strikes and exercise dates for the call and put legs.
+
+```python
+option = ql.ComplexChooserOption(
+    choosing_date, call_strike, put_strike, call_exercise, put_exercise,
+)
+```
+
+## Margrabe Options
+
+### MargrabeOption
+
+```{eval-rst}
+.. autoclass:: pyquantlib.MargrabeOption
+```
+
+Margrabe option (exchange option): the right to exchange one asset for another.
+
+```python
+option = ql.MargrabeOption(1, 1, exercise)
+option.setPricingEngine(engine)
+print(option.delta1(), option.delta2())
+print(option.gamma1(), option.gamma2())
+```
+
+## Forward-Start Options
+
+### ForwardVanillaOption
+
+```{eval-rst}
+.. autoclass:: pyquantlib.ForwardVanillaOption
+```
+
+Forward-start vanilla option. The strike is set at a future reset date based on a moneyness ratio.
+
+```python
+option = ql.ForwardVanillaOption(1.0, reset_date, payoff, exercise)
+```
+
+## Quanto Options
+
+### QuantoVanillaOption
+
+```{eval-rst}
+.. autoclass:: pyquantlib.QuantoVanillaOption
+```
+
+Quanto vanilla option with currency adjustment. Provides quanto-specific greeks: `qvega()`, `qrho()`, `qlambda()`.
+
+```python
+option = ql.QuantoVanillaOption(payoff, exercise)
+option.setPricingEngine(engine)
+print(option.qvega(), option.qrho(), option.qlambda())
+```
+
 ## Payoffs
 
+### FloatingTypePayoff
+
+```{eval-rst}
+.. autoclass:: pyquantlib.FloatingTypePayoff
+```
+
+Floating-strike payoff for lookback options.
+
+```python
+payoff = ql.FloatingTypePayoff(ql.Call)
+```
+
 ### PlainVanillaPayoff
 
 ```{eval-rst}

docs/api/pricingengines.md

@@ -370,6 +370,131 @@ engine = ql.MCDiscreteArithmeticAPEngine(
 )
 ```
 
+## Lookback Engines
+
+### AnalyticContinuousFloatingLookbackEngine
+
+```{eval-rst}
+.. autoclass:: pyquantlib.AnalyticContinuousFloatingLookbackEngine
+```
+
+### AnalyticContinuousFixedLookbackEngine
+
+```{eval-rst}
+.. autoclass:: pyquantlib.AnalyticContinuousFixedLookbackEngine
+```
+
+### AnalyticContinuousPartialFloatingLookbackEngine
+
+```{eval-rst}
+.. autoclass:: pyquantlib.AnalyticContinuousPartialFloatingLookbackEngine
+```
+
+### AnalyticContinuousPartialFixedLookbackEngine
+
+```{eval-rst}
+.. autoclass:: pyquantlib.AnalyticContinuousPartialFixedLookbackEngine
+```
+
+```python
+payoff = ql.FloatingTypePayoff(ql.Call)
+exercise = ql.EuropeanExercise(expiry)
+option = ql.ContinuousFloatingLookbackOption(100.0, payoff, exercise)
+option.setPricingEngine(ql.AnalyticContinuousFloatingLookbackEngine(process))
+print(option.NPV())
+```
+
+## Cliquet Engines
+
+### AnalyticCliquetEngine
+
+```{eval-rst}
+.. autoclass:: pyquantlib.AnalyticCliquetEngine
+```
+
+```python
+engine = ql.AnalyticCliquetEngine(process)
+cliquet.setPricingEngine(engine)
+print(cliquet.NPV())
+```
+
+## Exotic Engines
+
+### AnalyticCompoundOptionEngine
+
+```{eval-rst}
+.. autoclass:: pyquantlib.AnalyticCompoundOptionEngine
+```
+
+### AnalyticSimpleChooserEngine
+
+```{eval-rst}
+.. autoclass:: pyquantlib.AnalyticSimpleChooserEngine
+```
+
+### AnalyticComplexChooserEngine
+
+```{eval-rst}
+.. autoclass:: pyquantlib.AnalyticComplexChooserEngine
+```
+
+### AnalyticEuropeanMargrabeEngine
+
+```{eval-rst}
+.. autoclass:: pyquantlib.AnalyticEuropeanMargrabeEngine
+```
+
+Takes two Black-Scholes-Merton processes and a correlation parameter.
+
+```python
+engine = ql.AnalyticEuropeanMargrabeEngine(process1, process2, 0.5)
+option.setPricingEngine(engine)
+```
+
+### AnalyticAmericanMargrabeEngine
+
+```{eval-rst}
+.. autoclass:: pyquantlib.AnalyticAmericanMargrabeEngine
+```
+
+## Forward-Start Engines
+
+### ForwardEuropeanEngine
+
+```{eval-rst}
+.. autoclass:: pyquantlib.ForwardEuropeanEngine
+```
+
+### ForwardPerformanceEuropeanEngine
+
+```{eval-rst}
+.. autoclass:: pyquantlib.ForwardPerformanceEuropeanEngine
+```
+
+```python
+option = ql.ForwardVanillaOption(1.0, reset_date, payoff, exercise)
+option.setPricingEngine(ql.ForwardEuropeanEngine(process))
+print(option.NPV())
+```
+
+## Quanto Engines
+
+### QuantoVanillaEngine
+
+```{eval-rst}
+.. autoclass:: pyquantlib.QuantoVanillaEngine
+```
+
+Quanto European option engine (currency-adjusted Black-Scholes). Accepts explicit Handle arguments or raw objects (hidden handles).
+
+```python
+engine = ql.QuantoVanillaEngine(
+    process, foreign_rate, fx_vol, correlation,
+)
+option.setPricingEngine(engine)
+print(option.NPV(), option.qvega(), option.qrho(), option.qlambda())
+```
+
 ## Cap/Floor Engines
 
 ### BlackCapFloorEngine

docs/changelog.md

@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 #### Core
 - `Forward` ABC for forward contracts (in `pyquantlib.base`) with inspectors (`settlementDate`, `forwardValue`, `spotValue`, `spotIncome`, `impliedYield`)
 - `ForwardTypePayoff` for long/short forward payoffs
+- `FloatingTypePayoff` for floating-strike lookback options
 
 #### Indexes
 - `EquityIndex` with minimal, full Handle, and hidden-handle constructors
@@ -30,6 +31,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `SoftCallability` with trigger level for soft-call provisions
 - `ConvertibleBond` base class with `conversionRatio()` and `callability()`
 - `ConvertibleZeroCouponBond`, `ConvertibleFixedCouponBond`, `ConvertibleFloatingRateBond`
+- **Lookback options**: `ContinuousFloatingLookbackOption`, `ContinuousFixedLookbackOption`, `ContinuousPartialFloatingLookbackOption`, `ContinuousPartialFixedLookbackOption`
+- `CliquetOption` cliquet (ratchet) option with periodic resets
+- `CompoundOption` option on an option (mother/daughter)
+- `SimpleChooserOption` and `ComplexChooserOption` chooser options
+- `MargrabeOption` exchange option with `delta1()`, `delta2()`, `gamma1()`, `gamma2()`
+- `ForwardVanillaOption` forward-start vanilla option
+- `QuantoVanillaOption` quanto option with `qvega()`, `qrho()`, `qlambda()`
 
 #### Cash Flows
 - `Dividend` ABC (in `pyquantlib.base`) for custom dividend implementations
@@ -39,6 +47,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 #### Pricing Engines
 - `BinomialConvertibleEngine` Tsiveriotis-Fernandes lattice engine for convertible bonds (7 tree types: jr, crr, eqp, trigeorgis, tian, lr, joshi)
+- **Lookback engines**: `AnalyticContinuousFloatingLookbackEngine`, `AnalyticContinuousFixedLookbackEngine`, `AnalyticContinuousPartialFloatingLookbackEngine`, `AnalyticContinuousPartialFixedLookbackEngine`
+- `AnalyticCliquetEngine` analytic cliquet option engine
+- `AnalyticCompoundOptionEngine` analytic compound option engine
+- `AnalyticSimpleChooserEngine` and `AnalyticComplexChooserEngine` chooser option engines
+- `AnalyticEuropeanMargrabeEngine` and `AnalyticAmericanMargrabeEngine` exchange option engines
+- `ForwardEuropeanEngine` and `ForwardPerformanceEuropeanEngine` forward-start option engines
+- `QuantoVanillaEngine` quanto European option engine with hidden handle constructors
 
 #### Experimental
 - `CallableBond` ABC (in `pyquantlib.base`) with OAS, effective duration/convexity, implied volatility