> ## Documentation Index
> Fetch the complete documentation index at: https://docs.effectiveai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# relativities.models

> Every public name in relativities.models, from its docstrings.

*Generated from the package's Python API.*

Small, inspectable statistical models with explicit actuarial meanings.

Poisson models predict counts, optionally over a supplied exposure. Gamma models
predict positive individual claim severities. Both use a log link and numeric
features. Both predict individual records; aggregate loss and parameter
uncertainty are outside their scope.

## ConditionalDistribution

```python theme={null}
class ConditionalDistribution(
    family: Literal['poisson', 'gamma'],
    means: tuple[tuple[RecordId, float], ...],
    dispersion: float = 1.0,
)
```

One distribution per successfully predicted record, aligned by identity.

Poisson values describe counts over each record's exposure. Gamma values
describe a positive individual severity, one claim at a time.

### ConditionalDistribution.mean

```python theme={null}
def mean(self) -> dict[RecordId, float]
```

Each predicted record's conditional mean, by identity.

### ConditionalDistribution.quantile

```python theme={null}
def quantile(self, probability: float) -> dict[RecordId, float]
```

Return outcome quantiles of each record's distribution, as opposed to
confidence limits for the fitted mean.

### ConditionalDistribution.cdf

```python theme={null}
def cdf(self, value: float) -> dict[RecordId, float]
```

Return P(outcome \<= value) for every predicted record.

### ConditionalDistribution.survival

```python theme={null}
def survival(self, value: float) -> dict[RecordId, float]
```

Return P(outcome > value), retaining accuracy in the upper tail.

### ConditionalDistribution.sample

```python theme={null}
def sample(
    self,
    n: int,
    *,
    seed: int | None = None,
) -> dict[RecordId, tuple[float, ...]]
```

Return independent conditional draws; tuple position is the draw ID.

Independence is a sampling convention, separate from any estimated
portfolio dependence. Seeds reproduce draws for the same ordered inputs and
numerical-library versions. Draws are simulated values, separate from the
observed records.

## LossEvaluationReport

```python theme={null}
class LossEvaluationReport(
    target: str,
    unit: str,
    family: str,
    exposure: str | None,
    total_count: int,
    evaluated_count: int,
    observed_total: float,
    expected_total: float,
    mean_absolute_error: float | None,
    mean_deviance: float | None,
    failures: tuple[ResultRow, ...],
)
```

Holdout diagnostics for one loss model, from `evaluate_loss`.

Totals, mean absolute error and mean deviance cover the records that could
be evaluated, unweighted. Every excluded record is in `failures` with its
reason.

### LossEvaluationReport.summary

```python theme={null}
def summary(self) -> dict[str, object]
```

The report as a plain dict, with actual-to-expected, the weighting and the
metric denominator spelled out.

## LossModel

```python theme={null}
class LossModel(
    *,
    family: Literal['poisson', 'gamma'],
    features: Sequence[str],
    target: str,
    unit: str,
    output: str | None = None,
    exposure: str | None = None,
)
```

A Poisson frequency or Gamma severity GLM with a fixed log link.

`fit` returns a new model. Configuration and fitted parameters are immutable.
Predictors are explicit numeric columns, used as given, with formulas and
learned preprocessing out of scope. Everything a prediction needs lives in
the persisted model.

### LossModel.fitted

```python theme={null}
@property
def fitted(self) -> bool
```

Whether the model has fitted parameters.

### LossModel.metadata

```python theme={null}
@property
def metadata(self) -> dict[str, object]
```

What the model is and what its predictions mean: configuration, link,
prediction meaning, uncertainty and fit.

### LossModel.input\_schema

```python theme={null}
@property
def input_schema(self) -> dict[str, object]
```

The JSON Schema of one prediction input: each feature, and the exposure.

### LossModel.output\_schema

```python theme={null}
@property
def output_schema(self) -> dict[str, object]
```

The JSON Schema of one prediction: the conditional expected value, in `unit`.

### LossModel.coefficients

```python theme={null}
@property
def coefficients(self) -> dict[str, float]
```

The fitted coefficients by name, `intercept` first.

### LossModel.fit

```python theme={null}
def fit(self, training: Dataset) -> LossModel
```

Fit unweighted observations; exposure is an offset, and every observation weighs the same.

Missing/invalid observations fail fitting rather than silently changing
the training population. Gamma dispersion is the Pearson estimate.

### LossModel.**call**

```python theme={null}
def __call__(self, inputs: Inputs) -> LossResult
```

Predict every input, keeping its ID; a bad input is `prediction_failed`.

### LossModel.save

```python theme={null}
def save(self, path: str | os.PathLike[str]) -> Path
```

Save parameters and configuration as plain JSON data, free of executable code.

### LossModel.load

```python theme={null}
@classmethod
def load(cls, path: str | os.PathLike[str]) -> LossModel
```

Load a local JSON artifact from a file path.

## LossResult

```python theme={null}
class LossResult(RatingResult)(
    rows: Iterable[ResultRow],
    *,
    distributions: Mapping[str, ConditionalDistribution],
    metadata: Mapping[str, object] | None = None,
)
```

Predicted means and conditional distributions, with every input retained.

### LossResult.distributions

```python theme={null}
@property
def distributions(self) -> Mapping[str, ConditionalDistribution]
```

Each output's conditional distribution, by output name.

## evaluate\_loss

```python theme={null}
def evaluate_loss(model: LossModel, data: Dataset) -> LossEvaluationReport
```

Evaluate against caller-selected holdout data; the model keeps its fitted parameters.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.