loopable / platform /core /amazon_project_results.py
fsanyoto's picture
Deploy AIOS web (React glide grid + FastAPI slice)
a5981db verified
Raw History Blame Contribute Delete
12.7 kB
"""Typed project results and daily series with independent source reconciliation."""
from datetime import date, timedelta
import hashlib
import json
import math
import re
import uuid
from core import periods
METRICS = ('sales', 'units', 'returns', 'return_rate', 'refund_rate', 'roas')
GRAINS = ('sku', 'asin', 'parent_asin')
MAX_CONFIGS = 20
BOUNDARY = '[completedOn, endExclusive) in the tenant timezone. Today is excluded.'
SERIES_METRICS = (
('sales', 'Sales', 'currency'), ('units', 'Units', 'units'),
('margin', 'Margin', 'percent'), ('returns', 'Returns', 'units'),
('returns_pct', 'Returns %', 'percent'), ('refunds_pct', 'Refunds %', 'percent'),
('roas', 'ROAS', 'ratio'), ('sales_yoy', 'Sales YoY', 'percent'),
)
SERIES_BOUNDARY = 'Inclusive requested dates in the tenant timezone. Today is incomplete and excluded from totals.'
class ValidationFailed(RuntimeError):
"""A daily project series does not reconcile to its independent source aggregate."""
def series_scope(value='all'):
"""Parse the modal filter without allowing it to widen project membership."""
if value == 'all':
return None
if not isinstance(value, str) or ':' not in value:
raise ValueError('scope must be all, sku:<keys>, asin:<key> or parent:<key>.')
grain, text = value.split(':', 1)
keys = [key.strip() for key in text.split(',')]
if (grain not in ('sku', 'asin', 'parent') or not all(keys)
or (grain != 'sku' and len(keys) != 1)):
raise ValueError('scope must be all, sku:<keys>, asin:<key> or parent:<key>.')
return {'grain': grain, 'keys': list(dict.fromkeys(keys))}
def series_window(project, start=None, end=None, *, today=None):
"""Default to thirty days before start through today and aggregate only completed tenant days."""
today = today or periods.today()
def parsed(value):
if not isinstance(value, str) or not re.fullmatch(r'\d{4}-\d{2}-\d{2}', value):
raise ValueError('Series dates must use YYYY-MM-DD.')
return date.fromisoformat(value)
first = (parsed(start) if start is not None else
parsed(project.get('start_on') or today.isoformat()) - timedelta(days=30))
last = parsed(end) if end is not None else today
if first > last or last > today:
raise ValueError('Series dates must be ordered and cannot end after today.')
stop = min(last + timedelta(days=1), today)
lo, hi, rule = periods.yoy_window(first.isoformat(), stop.isoformat(), 'day')
return {'from': first.isoformat(), 'to': last.isoformat(), 'days': (stop - first).days,
'current': (first, stop), 'comparison': (date.fromisoformat(lo), date.fromisoformat(hi)),
'compare_rule': rule}
def _finite(value):
return isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value)
def validate(answer, *, independent):
"""Requery independent totals and return failing checks for any changed or unproved series."""
checks = []
first, last = date.fromisoformat(answer['from']), date.fromisoformat(answer['to'])
dates = [(first + timedelta(days=i)).isoformat() for i in range((last - first).days + 1)]
expected_keys = [key for key, _label, _unit in SERIES_METRICS]
metrics = answer['metrics']
if [metric['key'] for metric in metrics] != expected_keys:
return [{'check': 'series total ties to economics', 'ok': False,
'reason': 'Series metrics do not follow the project result contract.'}]
for metric in metrics:
ours = metric.get('total')
source = independent(metric['key'])
expected, source_reason = source['value'], source.get('reason')
points = metric.get('points', [])
ok = [point.get('date') for point in points] == dates
if ours is None:
ok = ok and bool(metric.get('reason')) and all(point.get('value') is None for point in points)
else:
ok = (ok and _finite(ours) and _finite(expected)
and math.isclose(ours, expected, rel_tol=1e-9, abs_tol=1e-6)
and all(point.get('value') is None or _finite(point['value']) for point in points))
if metric['key'] in ('sales', 'units', 'returns'):
values = [point['value'] for point in points if point.get('value') is not None]
ok = ok and bool(values) and math.isclose(math.fsum(values), ours, rel_tol=1e-9, abs_tol=1e-6)
tie = metric.get('tie', {})
if tie.get('ok') or tie.get('ours') is not None or tie.get('independent') is not None:
ok = (ok and ours is not None and tie.get('ok') is True
and _finite(tie.get('ours')) and _finite(tie.get('independent'))
and math.isclose(tie['ours'], ours, rel_tol=1e-9, abs_tol=1e-6)
and _finite(expected)
and math.isclose(tie['independent'], expected, rel_tol=1e-9, abs_tol=1e-6))
checks.append({'check': 'series total ties to economics', 'metric': metric['key'], 'ok': bool(ok),
'ours': ours, 'independent': expected,
'reason': metric.get('reason') or source_reason})
return checks
def series(project, *, bounds, read, independent):
"""Publish the fixed chart order and project markers after independent economics reconciliation."""
first, last = date.fromisoformat(bounds['from']), date.fromisoformat(bounds['to'])
dates = [(first + timedelta(days=i)).isoformat() for i in range((last - first).days + 1)]
answer = {'projectId': project['id'], 'from': bounds['from'], 'to': bounds['to'],
'timezone': timezone_name(), 'boundary': SERIES_BOUNDARY,
'markers': {'start': project.get('start_on'), 'target': project.get('target_on'),
'completed': project.get('completed_on')}, 'metrics': []}
for key, label, unit in SERIES_METRICS:
measured = read(key)
total, reason = measured.get('total'), measured.get('reason')
if total is None and not reason:
reason = 'An independent daily source for this metric is unavailable.'
values = {point['date']: point['value'] for point in measured.get('points', [])} if total is not None else {}
answer['metrics'].append({'key': key, 'label': label, 'unit': measured.get('unit', unit),
'points': [{'date': day, 'value': values.get(day)} for day in dates],
'total': total, 'reason': reason,
'tie': {'ok': False, 'ours': None, 'independent': None}})
checks = validate(answer, independent=independent)
if any(not check['ok'] for check in checks):
raise ValidationFailed('A series total does not tie to its independent Amazon economics aggregate.')
for metric, check in zip(answer['metrics'], checks):
if metric['total'] is not None:
metric['tie'] = {'ok': True, 'ours': check['ours'], 'independent': check['independent']}
return answer
def configurations(values):
"""Normalize an ordered list of supported metrics without accepting executable expressions."""
if not isinstance(values, (list, tuple)) or len(values) > MAX_CONFIGS:
raise ValueError(f'resultConfigs must be a list of at most {MAX_CONFIGS} configurations.')
out, seen = [], set()
for item in values:
if not isinstance(item, dict) or set(item) - {'id', 'metric', 'grain', 'window', 'days', 'compare'}:
raise ValueError('Each result configuration must contain only typed result fields.')
identity = item.get('id', uuid.uuid4().hex)
if (not isinstance(identity, str) or not re.fullmatch(r'[A-Za-z0-9_-]{1,64}', identity)
or identity in seen):
raise ValueError('Result configuration ids must be unique text identifiers.')
metric, grain = item.get('metric'), item.get('grain', 'sku')
window, compare = item.get('window', 'fixed'), item.get('compare', 'prior')
days = item.get('days', 7)
if metric not in METRICS or grain not in GRAINS:
raise ValueError('Select a supported Amazon metric and target grain.')
if window not in ('fixed', 'completion_to_now') or compare not in ('prior', 'yoy'):
raise ValueError('Select a supported result window and comparison.')
if type(days) is not int or not 1 <= days <= 366:
raise ValueError('Result days must be a whole number from 1 to 366.')
out.append(dict(id=identity, metric=metric, grain=grain, window=window, days=days, compare=compare))
seen.add(identity)
return out
def timezone_name():
"""Return the effective tenant business timezone, including the shared UTC fallback."""
return getattr(periods._business_zone(), 'key', 'UTC')
def windows(project, config, today=None):
"""Anchor equal comparison windows to completion and exclude the tenant's incomplete day."""
today = today or periods.today()
base = {'state': 'waiting_for_completion', 'days': 0, 'boundary': BOUNDARY}
if project.get('status') != 'Completed' or not project.get('completed_on'):
return base
start = date.fromisoformat(project['completed_on'])
if start > today:
raise ValueError('completedOn cannot be in the future.')
if start == today:
return {**base, 'state': 'waiting_for_completed_day'}
end = today if config['window'] == 'completion_to_now' else start + timedelta(days=config['days'])
if end > today:
return {**base, 'state': 'waiting_for_window', 'availableDays': (today - start).days,
'requestedDays': config['days']}
days = (end - start).days
if config['compare'] == 'yoy':
lo, hi, rule = periods.yoy_window(start.isoformat(), end.isoformat(), 'day')
prior = (date.fromisoformat(lo), date.fromisoformat(hi))
else:
prior, rule = (start - timedelta(days=days), start), None
return {**base, 'state': 'ready', 'days': days, 'current': (start, end), 'comparison': prior,
'compare_rule': rule}
def anchor(project, targets, today, zone):
"""Identify the complete completion, configuration, target and tenant-day input set."""
values = {'status': project['status'], 'completedOn': project.get('completed_on'),
'configs': project.get('result_configs', []),
'targets': sorted({(t['grain'], t['key']) for t in targets}),
'today': today.isoformat(), 'timezone': zone}
return hashlib.sha256(json.dumps(values, sort_keys=True, separators=(',', ':')).encode()).hexdigest()
def results(project, targets, *, read, metadata, today=None):
"""Publish reconciled figures only after deriving their current completion and target anchor."""
today, zone = today or periods.today(), timezone_name()
out = {'projectId': project['id'], 'timezone': zone, 'boundary': BOUNDARY,
'anchor': anchor(project, targets, today, zone), 'results': []}
for config in configurations(project.get('result_configs', [])):
bounds = windows(project, config, today)
entry = {'config': config, **metadata(config['metric']), 'state': bounds['state'],
'current': None, 'comparison': None, 'series': [], 'scope': None,
'delta': None, 'deltaPercent': None, 'reason': None,
'compare_rule': bounds.get('compare_rule')}
if bounds['state'] == 'ready':
figure = read(config, bounds)
entry.update(figure)
current, prior = figure.get('current'), figure.get('comparison')
if current is not None and prior is not None:
entry['series'] = current.get('series', [])
states = [current['status'], prior['status']]
entry['state'] = next((state for state in ('unavailable', 'no_prior_data', 'partial_data')
if state in states), 'ready')
entry['reason'] = current.get('reason') or prior.get('reason')
if all(w.get('validated') and w.get('status') == 'available' for w in (current, prior)):
a, b = current['value'], prior['value']
if a is not None and b is not None and all(math.isfinite(v) for v in (a, b)):
change = a - b
entry['delta'] = change if math.isfinite(change) else None
percent = 100 * change / b if b > 0 else None
entry['deltaPercent'] = percent if percent is not None and math.isfinite(percent) else None
out['results'].append(entry)
return out