"""Seer documentation examples. Synthetic inputs; no network, credentials or trades.

Run with Python 3.10+: python3 examples.py
These functions illustrate numerical semantics, not production service implementations.
"""
from datetime import datetime
from math import isfinite, log, sqrt
from statistics import stdev


def annualized_volatility(prices, periods_per_year=252):
    if len(prices) < 3 or any(not isfinite(p) or p <= 0 for p in prices):
        raise ValueError("Need at least three finite positive prices")
    if not isfinite(periods_per_year) or periods_per_year <= 0:
        raise ValueError("Invalid annualization convention")
    returns = [log(b) - log(a) for a, b in zip(prices, prices[1:])]
    return stdev(returns) * sqrt(periods_per_year)


def reserve(available_atoms, committed_atoms, amount_atoms):
    values = (available_atoms, committed_atoms, amount_atoms)
    if any(type(v) is not int or v < 0 for v in values):
        raise ValueError("Expected nonnegative integer atoms")
    if amount_atoms > available_atoms:
        raise ValueError("Insufficient available balance")
    return available_atoms - amount_atoms, committed_atoms + amount_atoms


def pinball(outcome, quantile, level):
    if not all(isfinite(v) for v in (outcome, quantile, level)) or not 0 < level < 1:
        raise ValueError("Finite values and a quantile level in (0, 1) required")
    return (level - int(outcome < quantile)) * (outcome - quantile)


def brier(probabilities, outcomes):
    if not probabilities or len(probabilities) != len(outcomes):
        raise ValueError("Need paired, nonempty observations")
    if any(not isfinite(p) or not 0 <= p <= 1 for p in probabilities):
        raise ValueError("Probabilities must be finite and within [0, 1]")
    if any(o not in (0, 1) for o in outcomes):
        raise ValueError("Binary outcomes required")
    return sum((p-o)**2 for p,o in zip(probabilities,outcomes)) / len(outcomes)


def eligible_at(available_at, decision_at):
    """Temporal predicate only. Access rights and quality are separate checks."""
    times = [datetime.fromisoformat(v.replace('Z','+00:00')) for v in (available_at,decision_at)]
    if any(t.tzinfo is None or t.utcoffset() is None for t in times):
        raise ValueError("Explicit timestamp offsets required")
    return times[0] <= times[1]


if __name__ == '__main__':
    print('Synthetic examples, not forecasts or live financial activity.')
    print('Annualized sample log-return volatility:', round(annualized_volatility([100,102,101,104]),6))
    print('Reserve 20 SCC from 150 SCC, at illustrative scale 2:', reserve(15000,0,2000))
    print('Brier score:', brier([0.8,0.3],[1,0]))
    print('0.9-quantile pinball loss:', pinball(0.02,0.03,0.9))
    print('Later revision eligible for earlier decision:', eligible_at('2026-10-02T12:00:00Z','2026-10-01T12:00:00Z'))