skills/sovrano-sponsorship-analysis/calculator-inputs.md

# Calculator inputs

`get_sovrano_calculator_guide` returns the supported types, units, preset assumptions and example requests. This file carries the meaning of the inputs and the rules the schemas do not enforce.

Use `model_sponsorship_package_from_presets` for the preset shape, `model_sponsorship_package_with_rates` for explicit rates and `calculate_sovrano_package_value` for a documented package ID. Each tool takes one `package` object. Periods are months for explicit rates. Presets use a one-event window, not recurring monthly rights. Fees can be null.

## Presets

```json
{
  "package": {
    "id": "offer-a",
    "currency_assumption": "CHF",
    "fee": null,
    "items": [
      {"id":"social", "label":"Guaranteed branded posts", "type":"BRANDED_SOCIAL_POSTS", "quantity":6,
       "quantity_basis":{"origin":"proposal_claim", "reference":"Supplied proposal, page 4; date not stated"}},
      {"id":"exclusivity", "label":"Category exclusivity", "type":"UNPRICED", "quantity":null,
       "quantity_basis":{"origin":"proposal_claim", "reference":"Supplied proposal, page 5; scope unspecified"}}
    ]
  }
}
```

`quantity_basis` always carries a reference or rationale. A `rate_override` is echoed as an agent-supplied assumption; verified evidence carries its source in the rationale. For a one-event fee, `fee.period_months: 1` is the comparison-window convention; a multi-year fee is annualised first, and the conversion is stated.

## Preserve a baseline; submit a separate revision

A revision is a second plain request: a fresh object with the same asset IDs, quantities, units and scope, changing only the intended assumptions. The two requests below are a synthetic technical example; market rates come from research. The placeholder URL stands in for a researched source: in real research replace it with applicable dated evidence and its rationale, or keep the original model.

Baseline:

```json
{"package":{"id":"example-baseline","currency_assumption":"CHF","fee":null,"items":[{"id":"vip","label":"Ten VIP passes for one event","type":"VIP_PASSES","quantity":10,"quantity_basis":{"origin":"agent_scenario","reference":"Synthetic one-event example dated 2026-09-01, not commercial evidence"}}]}}
```

Separate revised scenario:

```json
{"package":{"id":"example-revised","currency_assumption":"CHF","fee":null,"items":[{"id":"vip","label":"Ten VIP passes for one event","type":"VIP_PASSES","quantity":10,"quantity_basis":{"origin":"agent_scenario","reference":"Synthetic one-event example dated 2026-09-01, not commercial evidence"},"rate_override":{"conservative":100,"moderate":150,"aggressive":200,"source_date":"2026-09-01","source_url":"https://example.com/controlled-fixture","rationale":"Synthetic technical example only: CHF per VIP pass for one event; same quantity and scope as baseline. Placeholder reference, not researched or verified market evidence. Only rates change; no FX or geographic calibration."}}]}}
```

## Explicit rates

```json
{
  "package": {
    "id": "hypothetical-package", "currency": "CHF", "period_months": 12,
    "fee": {"amount":250000, "currency":"CHF", "period_months":12},
    "items": [{
      "id":"hospitality", "label":"Proposed hospitality passes", "pillar":"Experiential",
      "quantity":100, "unit":"passes",
      "rates": {"conservative":200, "moderate":300, "aggressive":400,
        "origin":"scenario_input", "assumption_id":"hospitality-rate-1",
        "rationale":"Illustrative agent what-if, not a researched market rate or seller commitment",
        "currency":"CHF", "unit":"passes", "period_months":12}
    }]
  }
}
```

The example numbers are hypothetical; real requests carry their own rates. Meanings the schema leaves to the agent:

- Rates are positive and ordered: conservative at most moderate, moderate at most aggressive.
- A null quantity or rate preserves an unvalued right. A zero quantity explicitly excludes it.
- Units, currency and period must match the rate, or the line stays unvalued.
- A fee in another currency needs a separately researched, dated FX assumption before resubmission. State the conversion beside the rate.
- Period proration assumes the rights repeat unchanged. Check that assumption before using the ratio.
- Each rate carries a unique assumption ID and a rationale. Dated source references go in the rationale.

Read the scenario line contributions, `assumptions_ledger`, `unvalued_items`, `limitations`, `fee_comparison` and coverage. A partial subtotal stays labelled partial. Strategic fit is the agent's judgment.

`interpretation_support.valued_items` ranks moderate contributions and shares of the valued subtotal. Its checklist prompts are research candidates; the document may already answer them. Unvalued rights have no rank. Investigate the most consequential, least-supported assumptions, including unvalued rights, rather than the largest number.

## Database mode

After selecting a real package ID, call `calculate_sovrano_package_value` with `{"package":{"package_id":27,"currency":"CHF"}}`. Published asks, calculated component value and independent asking-price estimates keep separate meanings and together inform the decision. The returned audience context is the property's audience; sponsor exposure is a separate, justified input.